BeagleBoard/GSoC/2010 Projects/C6Run/Documentation

From eLinux.org
< BeagleBoard‎ | GSoC‎ | 2010 Projects‎ | C6Run
Revision as of 14:28, 10 August 2010 by Maltanar (Talk | contribs) (Structure of the RPC Package)

Jump to: navigation, search

Project Overview

DSP-RPC-POSIX is a component of the C6Run project which allows you to do DSP->GPP remote procedure calls - that is, you can invoke functions/code residing somewhere on the GPP side directly from the DSP as if you were accessing a local function (there are, of course, certain requirements and restrictions).

"What functions are available on the GPP side, then?" one might ask. The answer is pretty much "everything that the hardware can do" or "everything you can do in your regular operating system" or something along the lines of that. From basic tasks like accessing the file system to more sophisticated things like sending a file over FTP, there's a myriad of possibilities.

Two reasons as to why DSP->GPP RPC is desireable would be: access to otherwise (directly) inaccessible features and being able to reuse existing code. The reason why C6RunApp exists is because it's messy to write and run code for the DSP, especially if all you want to do is try out or experiment with things (prototyping). C6RunApp makes your life easier as a DSP-side developer by offering you easy compilation/running and access to console I/O (which is actually a limited form of RPC); DSP-RPC-POSIX expands this by granting you access to virtually any existing functionality you have on the GPP side.

How RPC Works

Step-by-step RPC Events

Let's start by some definitions:

DSP-side application - this is what you're assumed to be currently working on, which you compile with the C6Run script and will work on the DSP.

GPP-side application - sets up the DSP app and starts running it, and then "answers" the RPC requests. C6Run actually generates this for you, so you don't have to worry about anything here.

RPC target - a function which resides somewhere in the GPP side (could be a library, a shared library, your own code, etc.)

DSP-side stub - a little wrapper function which looks identical to the RPC target. it causes the RPC target to be executed with the parameters you passed to it, and returns you the same value it returns. this is what you actually call from the DSP-side. can be produced by the c6runapp-rpcgen tool, or written manually.

GPP-side stub - another little wrapper function on the GPP side, this is what the GPP side application actually calls. this function "knows" how to call the RPC target itself, so it executes that call and gets the result. can be produced by the c6runapp-rpcgen tool, or written manually.


The run of events that occur when you want to do a remote procedure call are as follows:


  1. From inside the DSP-side application, the DSP-side stub is called (which looks identical to the RPC target)
  2. The DSP-side stub is executed. It initializes the RPC request, and copies all the parameters into the request package (called "marshalling"), and signals for the RPC to be performed.
  3. The request package is sent to the GPP-side application using the RPC transport.
  4. The GPP-side application receives the package, unpacks it and extracts the parameters into a buffer (called "unmarshalling"). Some extra processing such as address translation for buffer/pointer parameters may be carried out at this step.
  5. The GPP-side application locates the relevant GPP-side stub and executes it.
  6. The GPP-side stub executes the RPC target, using the provided parameters, then stores the return value into another buffer. Some extra processing regarding structures or non-shared buffer return types may be carried out at this step.
  7. The GPP-side application sends back the result to the DSP-side.
  8. The DSP-side stub receives the result in the buffer, extracts and returns it to the user code.

Structure of the RPC Package

The buffer carrying a RPC request is structured as follows:

    4      NameLen         4          SignatureLen    ...      1
+----------+--------+----------------+-------------+----------+---+

|  NameLen |  Name  |  SignatureLen  |  Signature  |  Params  | 0 |

+----------+--------+----------------+-------------+----------+---+

  • NameLen: length of the function name
  • Name: function name of the GPP-side stub to be executed (observe: NOT the name of the RPC target)
  • SignatureLen: length of the function signature
  • Signature: function signature describing how the parameters section will be unpacked
  • Params: the function parameters, packed without any size promotions or alignment
  • 0: the null-terminating zero signalling the end of the package