BeagleBoard/GSoC/beagle offloader

=Proposal Template =

A short summary of the idea will go here

Student: Akshay Gahlot

Mentors: Zubeen Tolani

Code: N/A

Wiki: @Beagle-Offloader

=Status= This project is currently just a proposal.

=Proposal= I have completed the task required as described on Ideas page, and created a pull request, as listed here.

About me
IRC: Akki Github: Akshay9414 School: IIT Delhi Country: India Primary language: English and Hindi Typical work hours: 11AM-5PM and 9PM-2AM, Indian Standard Time(+5:30) Previous GSoC participation: No I haven't participated before.

I am highly fascinated by the capabilities of Beaglebone and want to exploit it to its full potential to make better and better Real Systems (particularly Robots). I believe working under the guidance of helpful people that would able me to learn in a better way and make me contribute more to the open source community.

About your project
Title: PRUs to offload processing of raw data from on-board Peripherals (Beagle-Offloader)

Inspiration
The Beaglebone is equipped with a number of peripherals to interact with surrounding systems like UART for Asynchronous Serial Communication, GPIO for receiving/sending signals from/to any other device, McSPI etc. Many hobbyists who want to perform heavy tasks with data of these peripherals, would like to have the MPU perform only those heavy tasks/calculations along with a separate module which is capable of handling the task of processing raw data and put down the processed data at some location where the MPU can easily access it, thus saving time. As a choice, one would prefer a separate module which is very fast for processing raw data and produces a better Real-Time System than the one having MPU performing all the tasks.

Solution
BeagleBone Black's AM335x SoC, has a subsystem called PRU-ICSS, with its two independent, 32 bit RISC cores, called PRUs, located in it. The cores are designed for low latency access to the GPIs and GPOs and have a rich memory arrangement to store the data. Also, having two such cores can be very useful, as both possess the power to sampling the data at very high frequency. The PRUSS subsystem fulfills the criteria of a fast separate module given the conditions it is configured/programmed to fetch data directly from the peripherals.

Goal for the Project
The goal is to be able to access on-board peripherals like the McSPI, McASP etc from the PRUs and to be able to use fetch data directly from these peripherals. This will allow to offload processing of the Raw data onto the PRUs. This project will utilize two PRUs and perform the CPU’s intensive work of processing raw data, leaving the MPU with a lot of time to perform heavy tasks on this data, the task for which a general purpose OS actually is.

The project will involve developing the following: 1) Device Tree Overlays: Firstly, a device tree is essentially a text file that describes the hardware     to the kernel. Since many architectures do not have self-describing hardware, some sort of externally      supplied description is needed for the kernel to understand the system it is running on.  2) C libraries for the PRUs to connect to these peripherals 3) Develop Drivers to reserver the device on behalf of the PRUs

Available Software Resources
Pru software support package @PRU-support : The PRU Software Support Package is an add-on package that provides a framework and examples for developing software for the Programmable Real-time Unit subsystem and Industrial Communication Sub-System (PRU-ICSS) in the supported TI processors. The PRU-ICSS achieves deterministic, real-time processing, direct access to I/Os and meets ultra-low-latency requirements. This software package contains example PRU firmware code as well as application loader code for the host OS. The examples demonstrate the PRU capabilities to interact with and control the system and its resources. (Reference)

Approach
Beaglebone has quite a good number of peripherals like McSPI, UART, McASP, USB, I2C, eCAP, ePWM, eQEP, CAN, Ethernet Subsystem, LCD Controller, Touch Screen Controller etc.

In the allotted time, it would be expected of me to build C library support for as many peripherals as possible (which includes both internal and external peripherals ). I would aim at completing five peripherals completely, which includes writing C code, DTS file, Drivers, example code, basic documentation, testing the codes, fixing the bugs and further if time permits I would try to complete more peripherals.

Programming the PRU core is not terribly different from programming any other core because we now have a C compiler(clpru) from which we are able to write regular C code and perform tasks using PRU cores. Further using the functionality of remote_proc, which provides an interface for the kernel to load firmware into the PRU core(s) and provides basic control such as start and halt.

I will perform the task in the following the way: Write the C code and compile it with 'clpru'. Then output binary will be loaded into the instruction RAM of the PRUs using the pru_rproc module, which also copies the resource table into the PRU's data RAM space. The firmware uploaded in PRUs will fetch data from memory registers. For PRU integrated peripherals, we could use local memory registers, but in the case of other peripherals, we need to access global memory registers which occur via L3 & L4 interconnect.

As PRUs are remote processors and not the main processing unit and all the peripherals are controlled by drivers on the main processor. So when the PRU wants to access a peripheral, it might be off, since the MPU (main processing unit) don’t know about it. Moreover, the MPU doesn’t know PRU wants to access the peripheral. But then, a peripheral can be switched on by loading the concerned DTBO file. Now if for some reason, the MPU also wants to access the peripheral at the same time the PRU is using it then there would be a conflict and we have to write drivers to manage the situation but as of now I don’t have the solution so it is included in my learning period (before coding starts) to handle/manage resource sharing between different processors.

We can utilize RPMsg which is a message passing mechanism that requests resources through remote_proc. PRU-software support package provides RPMsg library which abstracts the communication to a point where a user’s code can be utilized by PRUs to communicate with the ARM core. Similarly, an interface called as rpmsg_pru can be used in user’s space to read/write from/to device in the file system to send/receive messages to/from PRU.

The above functionality is highly beneficial as an extension to the project as it allows us to fetch data from the PRU and send it to MPU (on request). This, in turn, will really achieve the task of sharing the load of MPU with PRUs.

Timeline
I would start working at my full pace from 6th May onwards (My Semester exams will be finished by 6th May). This phase

Now - May 4 (Before Result Declaration):

1) Study the PRU-software-support-package and write some basic code get more insight of its working.  2) Start writing basic programs for PRUs using remote_proc

May 4 - May 30 ( Community Bonding Period): To complete the project well in time I would utilize this time to improve my knowledge

1) Study the work on PRUs in previous GSoC projects like PRU-Framework, this will help me broadening my scope of thinking about the implementation of my project. 2) Study the architecture defined of all peripherals and listing out the details for all so as to save time during the final coding time. 3) During this period I will remain in constant touch with my mentor and the BB community.  I will remain active on IRC to discuss and finalize on the modifications (if any)  that needs to be on existing schemas and design of new schemas (if needed).  4) Thus with the help of my mentor I will become absolutely clear about my future goals, the final implementations that need to be done as well as the approach.

As the number of peripherals are good enough so I would be working for 55-60 hours per week or may be even more to complete as many as possible.I be sharing my progress with the mentors and will regularly write blogs.

Week 1 : (Unpacking Week) 1) Setup everything which includes flashing BB with required image and installing the required softwares.  2) Try a few basic examples like PRU_blinky to check the working of remote_proc. 3) Start off with writing C code for first peripheral i.e McSPI . Week 2 :  1) Basic framework OF McSPI will be completed in the first week. Further improvisation of the code including writing DTS files. 2) Start off with the second peripheral i.e UART. Week 3 :  1) Basic framework of UART will be completed in the first week. Further improvisation of the code including writing DTS files 2) Prepare example code with proper comments for other's understanding.  3) A buffer will be kept for unpredictable delays but if time allows then will start the work of writing the drivers. Week 4 : (First Evaluation) 1) Complete the work of writing drivers for at least one of them. 2) This week I would completely focus over testing my two peripherals. 3) Fixing the bugs and exception handling. Week 5 : Work of the previous weeks will decide the fate of what I will be doing this week. Good four weeks will shine their light on my future work as work will proceed much faster than before.  1) Start this week with writing C code for handling McASP peripheral. 2) This time I will try to complete McASP C code along with DTS file and detailed example. Week 6 :  1) This week's work would focus on writing C code to the handle USB subsystem using PRU along with its DTS file. 2) This period has been kept for any unpredictable delay. Week 7 : 1) This week's work would focus on writing C code the handle I2C protcol using PRU along with its DTS file. Week 8 : (Second Evaluation) 1) This week I will focus on testing of the modules along with writing example code. 2) Bugs fixing and exception handling. 3) Start writing the drivers for all. Week 9 : 1) First priority would be complete the drivers and test them. 2) Writing scripts with proper instructions to make life easier for others. Week 10:  1) More testing and basic documentation. 2) Will improvise the prepared modules until the mentor satisfies there is no more need or scope. 3) Will start working on more peripherals depending upon the situation and what mentor suggest. Week 11: 1) This period has been kept for avoiding any unpredictable delay  but if time allows then start the work of a new peripheral possibly eCAP. Week 12: (Final Evaluation)  1) Finalize the work and make proper documentation. 2) Update my repository with final modules. 3) Making the youtube installation and tutorial videos. 4) Submit my work for final evaluation.

=Experience and approach= I am a core team member of ROBOTICS CLUB IITD and represented my college for ABU NATIONAL ROBOCON INDIA 2017. During this period one of my tasks was to create an easy and user friendly platform like Arduino for BBB (so that anyone could code easily without worrying much about the backend details). Current Wiring Bone library (https://github.com/AbhraneelBera/wiringBone) supports almost all core actions and functions but is slow in terms of pin toggling. My work included integration of basic Arduino features from Wiring Bone along with additin of features of Libpruio (http://beagleboard.org/project/libpruio/) for fast pin control. I also extended my work and built new C libraries for using pins in eQEP mode for reading values of quadrature encoder and customising DTS file according to my need. In my "Digital Logic and System Design" course final project I wrote a UART protocol for Xilinx Atlys FPGA and demonstrated the working by finding the frequency components of an input audio signal using transforms and plotting them in MATLAB using the above mentioned serial communication protocol.

In my “Design Practices” I have learned various tools like Lexer, Parser , Debuggers, Multithreading.

In my “Data Structures and Algorithms” I learned various algorithms,organisation and computation of data using well defined structures.

In my “Computer Architecture” course I am currently working on a semester project to implement ARM-RISC instruction set on a BASYS-3 FPGA in VHDL programming. This has greatly improvised my understanding of working and design of ARM processor in a great detail. I have also learnt about assembly language to quiet a good extent.

I am an enthusiastic and hardworking student and have been able to prove myself on every occasion provided. I am a good learner and quite confident that I would be able to learn the required and complete my project in the allotted time.

=Contingency= In case of problem, I would search for it on google,stack-overflow,BB community or consult someone over IRC. But in the worst situations, Head of our Robotics Club Prof. Kolin Paul (@Kolin), whose field of study is Hardware and Embedded System Security will always be eager to help me along with some other seniors of our club. Also we have an Assistech Lab in our department ,headed by Prof. M Balakrishnan (@mbala) in which research scholars are available round the clock.

=Benefit= In a system with many input/output peripherals, it is a good practice to distribute the work among different cores (in case of multi core processor) or use two or more MCU communicating with each other and sharing the load rather than one doing all the task. In our case offloading raw data processing is helping in same manner by sharing the work of MPU. Moreover, Linux OS is not real time and can't handle real time events like interrupts where PRUs can be very useful. This project will help many BB developers to easily configure peripherals according to their needs and focus their time other things.

***Mentors!!! please add your Quote here.***

=Suggestions= If I am given the opportunity to work on this project, I am certain that my enthusiasm and skill set will make a meaningful contribution to Beaglebone community. I have no other commitments in the Summers and will work around 55-60 hours per week. It would be a great opportunity for me to work with Beaglebone community and I ensure utmost dedication and relentless cooperation for this project.