example code, extending RTIO

[ghost]

Context:

• In October I created a ticket to discuss an add-in architecture for ARTIQ gateware #147.
• This was discussed on the mailing list on 11/13/2015. Items E4, E5.
• At the Jan site-visit in Boulder we discussed this. Here's Ben Keitch's summary of the discussion.

Ben raised the issue of extending Artiq with custom HDL. He was worried
that despite being open source, only m-labs can contribute hardware
level drivers to the project. Joe was keen to see contributions from
other groups in the form of code and hardware designs, as well as cash.
Sebastien explained the process of extending the code. To add a
periphery it is necessary to first install Migen and read docs which
requires Sphinx to be working. HDL can be added with a wrapper in Migen.
However, this still leaves considerable effort in the core kernel code
(C) and Python compiler. 

Joe asked about a request he had filed on github to allow RTIO to be
extended across devices. Sebastien explained the issues around this.

**ACTION:** Joe will refile the request with better details.

As a starting point, I suggest creation of a pedagogical example to document how ARTIQ RTIO can be extended.

• Illustrate extension of RTIO by creating a simple KC705 PHY with the following properties.
  • ARTIQ API for setting state of GPIO_LED_0 and GPIO_LED_1 and single-bit register op2 at time t
  • MIGEN which implements a PHY that does the following
  • if op2 = 0 set GPIO_LED_2 = GPIO_LED_0 & GPIO_LED_1
  • if op2 = 1 set GPIO_LED_2 = GPIO_LED_0 | GPIO_LED_1
  • new RTIO channel and PHY that implements the previous
• Summarize in on-line documentation this example.
• Add all necessary changes to codebase in single commit so users can see what needs to get touched.

[jbqubit]

Recently discussed on mailing list. https://ssl.serverraum.org/lists-archive/artiq/2016-July/000957.html

[sbourdeauducq]

(OP "ghost" is Joe @jbqubit)