srenblad/artiq
1
0
Fork 0
forked from M-Labs/artiq
Code Pull Requests Activity

doc: insist that output() must be called on TTLInOut. Closes #297

Browse Source
This commit is contained in:
Sebastien Bourdeauducq 2016-03-01 00:28:40 +08:00
parent d0d56bd3fe
commit a1e1f2b387
2 changed files with 17 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
artiq/coredevice/ttl.py
View File

@ -91,6 +91,11 @@ class TTLInOut:
This should be used with bidirectional channels. This should be used with bidirectional channels.
Note that the channel is in input mode by default. If you need to drive a
signal, you must call ``output``. If the channel is in output mode most of
the time in your setup, it is a good idea to call ``output`` in the
startup kernel.
:param channel: channel number :param channel: channel number
""" """
def __init__(self, dmgr, channel): def __init__(self, dmgr, channel):
@ -107,12 +112,18 @@ class TTLInOut:
@kernel @kernel
def output(self): def output(self):
"""Set the direction to output.""" """Set the direction to output.
There must be a delay of at least one RTIO clock cycle before any
other command can be issued."""
self.set_oe(True) self.set_oe(True)
@kernel @kernel
def input(self): def input(self):
"""Set the direction to input.""" """Set the direction to input.
There must be a delay of at least one RTIO clock cycle before any
other command can be issued."""
self.set_oe(False) self.set_oe(False)
@kernel @kernel

4
doc/manual/getting_started_core.rst
View File

@ -108,6 +108,10 @@ Create a new file ``rtio.py`` containing the following: ::
delay(2*us) delay(2*us)
.. note::
If ``ttl0`` is a bidirectional channel (``TTLInOut``), it is in input (non-driving) mode by default. You need to call ``self.ttl0.output()`` as explained above for the LED.
Connect an oscilloscope or logic analyzer to TTL0 and run ``artiq_run.py led.py``. Notice that the generated signal's period is precisely 4 microseconds, and that it has a duty cycle of precisely 50%. This is not what you would expect if the delay and the pulse were implemented with CPU-controlled GPIO: overhead from the loop management, function calls, etc. would increase the signal's period, and asymmetry in the overhead would cause duty cycle distortion. Connect an oscilloscope or logic analyzer to TTL0 and run ``artiq_run.py led.py``. Notice that the generated signal's period is precisely 4 microseconds, and that it has a duty cycle of precisely 50%. This is not what you would expect if the delay and the pulse were implemented with CPU-controlled GPIO: overhead from the loop management, function calls, etc. would increase the signal's period, and asymmetry in the overhead would cause duty cycle distortion.
Instead, inside the core device, output timing is generated by the gateware and the CPU only programs switching commands with certain timestamps that the CPU computes. This guarantees precise timing as long as the CPU can keep generating timestamps that are increasing fast enough. In case it fails to do that (and attempts to program an event with a timestamp in the past), the :class:`artiq.coredevice.exceptions.RTIOUnderflow` exception is raised. The kernel causing it may catch it (using a regular ``try... except...`` construct), or it will be propagated to the host. Instead, inside the core device, output timing is generated by the gateware and the CPU only programs switching commands with certain timestamps that the CPU computes. This guarantees precise timing as long as the CPU can keep generating timestamps that are increasing fast enough. In case it fails to do that (and attempts to program an event with a timestamp in the past), the :class:`artiq.coredevice.exceptions.RTIOUnderflow` exception is raised. The kernel causing it may catch it (using a regular ``try... except...`` construct), or it will be propagated to the host.