<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
-<title>Pins and Buses</title>
-<meta name="author" content="Phil Buonadonna" />
+<title>Low-Level I/O</title>
+<meta name="author" content="Phil Buonadonna, Jonathan Hui" />
<style type="text/css">
/*
dd {
margin-bottom: 0.5em }
-/* Uncomment (& remove this text!) to get bold-faced definition list terms
-dt {
- font-weight: bold }
-*/
-
div.abstract {
margin: 2em 5em }
</style>
</head>
<body>
-<div class="document" id="pins-and-buses">
-<h1 class="title">Pins and Buses</h1>
+<div class="document" id="low-level-i-o">
+<h1 class="title">Low-Level I/O</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tr class="field"><th class="docinfo-name">Type:</th><td class="field-body">Documentary</td>
</tr>
<tr><th class="docinfo-name">Status:</th>
-<td>Draft</td></tr>
+<td>Final</td></tr>
<tr class="field"><th class="docinfo-name">TinyOS-Version:</th><td class="field-body">2.x</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
-<td>Phil Buonadonna</td></tr>
-<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">23-Jan-2006</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.2</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-07-12</td>
-</tr>
-<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
-</tr>
+<td>Phil Buonadonna, Jonathan Hui</td></tr>
</tbody>
</table>
<div class="note">
<div class="section">
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>The memo documents the TinyOS 2.x interfaces used for controlling
-digital IO functionality and digital interfaces other than serial
-communication covered in [tep113].</p>
+digital IO functionality and digital interfaces.</p>
</div>
<div class="section">
<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
<p>The canonical TinyOS device is likely to have a variety of digital
interfaces. These interfaces may be divided into two broad
-categories. The first are general purpose digital I/O lines (pins)
-for individual digital signals at physical pins on a chip or
-platform. The second are digital I/O interfaces that have predefined
-communication protocol formats. The two buses covered in this
-document are the Serial Peripheral Interface (SPI) and the
-Inter-Integrated Circuit (I2c) or Two-Wire interface. While there are
-likely other bus formats, we presume SPI and I2C to have the largest
-coverage. While the UART interface is also in this category, it is
-covered separately in [tep113].</p>
-<p>This memo documents the interfaces used for pins and the two buses.</p>
+categories. The first are general purpose digital I/O lines (pins) for
+individual digital signals at physical pins on a chip or platform. The
+second are digital I/O interfaces that have predefined communication
+protocol formats. The three buses covered in this document are the
+Serial Peripheral Interface (SPI), the Inter-Integrated Circuit (I2C)
+or Two-Wire interface, and the Universal Asynchronous
+Receiver/Transmitter (UART) interface. While there are likely other
+bus formats, we presume SPI, I2C, and UART to have the largest
+coverage.</p>
+<p>This memo documents the interfaces used for pins and the three buses.</p>
</div>
<div class="section">
<h1><a id="pins" name="pins">2. Pins</a></h1>
-<p>General Purpose I/O (GPIO) pins are single, versatile digital I/O signals
-individually controllable on a particular chip or platform. Each GPIO
-can be placed into either an input mode or an output mode. On
-some platforms a third 'tri-state' mode may exist, but this
-functionality is platform specific and will not be covered in this
-document.</p>
-<p>On many platforms, a physical pin may function as either a digital GPIO
-or another special function I/O such. Examples include ADC I/O or a bus
-I/O. Interfaces to configure the specific function of a pin are
+<p>General Purpose I/O (GPIO) pins are single, versatile digital I/O
+signals individually controllable on a particular chip or
+platform. Each GPIO can be placed into either an input mode or an
+output mode. On some platforms a third 'tri-state' mode may exist, but
+this functionality is platform specific and will not be covered in
+this document.</p>
+<p>On many platforms, a physical pin may function as either a digital
+GPIO or another special function I/O such. Examples include ADC I/O or
+a bus I/O. Interfaces to configure the specific function of a pin are
platform specific.</p>
<p>The objective of the interfaces described here is not to attempt to
cover all possibilities of GPIO functionality and features, but to
async command void toggle();
async command bool get();
async command void makeInput();
+ async command bool isInput();
async command void makeOutput();
+ async command bool isOutput();
}
</pre>
</div>
interface GpioInterrupt {
async command error_t enableRisingEdge();
+ async command bool isRisingEdgeEnabled();
async command error_t enableFallingEdge();
+ async command bool isFallingEdgeEnabled();
async command error_t disable();
async event void fired();
<p>Some platforms may have hardware support for such a feature. Other
platforms may emulate this capability using the SoftCaptureC
component. The interface makes not declaration of the precision or
-accuracy of the timestamp with respect to the associated GPIO event.</p>
+accuracy of the timestamp with respect to the associated GPIO
+event.</p>
<pre class="literal-block">
interface GpioCapture {
async command error_t captureRisingEdge();
+ async command bool isRisingEdgeEnabled();
async command error_t captureFallingEdge();
+ async command bool isFallingEdgeEnabled();
async event void captured(uint16_t time);
async command void disable();
asynchronous packet level interface. The byte level interface is
intended for short transactions (3-4 bytes) on the SPI bus.</p>
<pre class="literal-block">
-interface SPIByte {
- async command error_t write( uint8_t tx, uint8_t* rx );
+interface SpiByte {
+ async command uint8_t write( uint8_t tx );
}
</pre>
<p>The packet level interface is for larger bus transactions. The
-pointer/length interface permits use of hardware assist such as DMA.</p>
+pointer/length interface permits use of hardware assist such as
+DMA.</p>
<pre class="literal-block">
-interface SPIPacket {
-
+interface SpiPacket {
async command error_t send( uint8_t* txBuf, uint8_t* rxBuf, uint16_t len );
async event void sendDone( uint8_t* txBuf, uint8_t* rxBuf, uint16_t len,
- error_t error );
+ error_t error );
}
</pre>
</div>
<p>The Inter-Integrated Circuit (I2C) interface is another type of
digital bus that is often used for chip-to-chip communication. It is
also known as a two-wire interface.</p>
-<p>The I2CPacket interface provides for asynchronous Master mode communication on an
-I2C with application framed packets. It supports only single
-transfers with a start-stop condition around each transfer.</p>
+<p>The I2CPacket interface provides for asynchronous Master mode
+communication on an I2C with application framed packets. Individual
+I2C START-STOP events are controllable which allows the using
+component to do multiple calls within a single I2C transaction and
+permits multiple START sequences</p>
<p>Platforms providing I2C capability MUST provide this interface.</p>
<pre class="literal-block">
-interface I2CPacket {
- async command result_t readPacket(uint16_t _addr, uint8_t _length, uint8_t* _data);
- async command result_t writePacket(uint16_t _addr, uint8_t _length, uint8_t* _data);
- async event void readPacketDone(uint16_t addr, uint8_t length, uint8_t* data, result_t success);
- async event void writePacketDone(uint16_t addr, uint8_t length, uint8_t* data, result_t success);
+interface I2CPacket<addr_size> {
+ async command error_t read(i2c_flags_t flags, uint16_t addr, uint8_t length, u int8_t* data);
+ async event void readDone(error_t error, uint16_t addr, uint8_t length, uint8_t* data);
+ async command error_t write(i2c_flags_t flags, uint16_t addr, uint8_t length, uint8_t* data);
+ async event void writeDone(error_t error, uint16_t addr, uint8_t length, uint8_t* data)
+}
+</pre>
+<p>The interface is typed according to the addressing space the
+underlying implementation supports. Valid type values are below.</p>
+<pre class="literal-block">
+TI2CExtdAddr - Interfaces uses the extended (10-bit) addressing mode.
+TI2CBasicAddr - Interfaces uses the basic (7-bit) addressing mode.
+</pre>
+<p>The i2c_flags_t values are defined below. The flags define the
+behavior of the operation for the call being made. These values may be
+ORed together.</p>
+<pre class="literal-block">
+I2C_START - Transmit an I2C STOP at the beginning of the operation.
+I2C_STOP - Transmit an I2C STOP at the end of the operation. Cannot be used
+ with the I2C_ACK_END flag.
+I2C_ACK_END - ACK the last byte sent from the buffer. This flags is only valid
+ a write operation. Cannot be used with the I2C_STOP flag.
+</pre>
+</div>
+<div class="section">
+<h2><a id="uart" name="uart">3.3 UART</a></h2>
+<p>The Universal Asynchronous Receiver/Transmitter (UART) interface is a
+type of serial interconnect. The interface is "asynchronous" since it
+recovers timing from the data stream itself, rather than a separate
+control stream. The interface is split into an asynchronous multi-byte
+level interface and a synchronous single-byte level interface.</p>
+<p>The multi-byte level interface, UartStream, provides a split-phase
+interface for sending and receiving one or more bytes at a time. When
+receiving bytes, a byte-level interrupt can be enabled or an interrupt
+can be generated after receiving one or more bytes. The latter is
+intended to support use cases where the number of bytes to receive is
+already known. If the byte-level receive interrupt is enabled, the
+receive command MUST return FAIL. If a multi-byte receive interrupt is
+enabled, the enableReceiveInterrupt command MUST return FAIL.</p>
+<pre class="literal-block">
+interface UartStream {
+ async command error_t send( uint8_t* buf, uint16_t len );
+ async event void sendDone( uint8_t* buf, uint16_t len, error_t error );
+
+ async command error_t enableReceiveInterrupt();
+ async command error_t disableReceiveInterrupt();
+ async event void receivedByte( uint8_t byte );
+
+ async command error_t receive( uint8_t* buf, uint8_t len );
+ async event void receiveDone( uint8_t* buf, uint16_t len, error_t error );
+}
+</pre>
+<p>The single-byte level interface, UartByte, provides a synchronous
+interface for sending and receiving a single byte. This interface is
+intended to support use cases with short transactions. Because UART is
+asynchronous, the receive command takes a timeout which represents
+units in byte-times, after which the command returns with an
+error. Note that use of this interface is discouraged if the UART baud
+rate is low.</p>
+<pre class="literal-block">
+interface UartByte {
+ async command error_t send( uint8_t byte );
+ async command error_t receive( uint8_t* byte, uint8_t timeout );
}
</pre>
</div>
</div>
<div class="section">
-<h1><a id="author-s-address" name="author-s-address">4. Author's Address</a></h1>
+<h1><a id="implementation" name="implementation">4. Implementation</a></h1>
+<p>Example implementations of the pin interfaces can be found in tos/chips/msp430/pins,
+tos/chips/atm128/pins, and tos/chips/pxa27x/gpio.</p>
+<p>Example implementations of the SPI interfaces can be found in tos/chips/msp430/usart,
+tos/chips/atm128/spi, and tos/chips/pxa27x/ssp.</p>
+<p>Example implementations of the I2C interfaces can be found in tos/chips/msp430/usart,
+tos/chips/atm128/i2c, and tos/chips/pxa27x/i2c.</p>
+<p>Example implementations of the UART interfaces can be found in tos/chips/msp430/usart,
+tos/chips/atm128/uart/ and tos/chips/pxa27x/uart.</p>
+</div>
+<div class="section">
+<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Phil Buonadonna</div>
-<div class="line">Arched Rock Corporation</div>
+<div class="line">Arch Rock Corporation</div>
<div class="line">657 Mission St. Ste 600</div>
<div class="line">San Francisco, CA 94105-4120</div>
<div class="line"><br /></div>
<div class="line">phone - +1 415 692-0828 x2833</div>
+<div class="line"><br /></div>
+<div class="line"><br /></div>
+<div class="line">Jonathan Hui</div>
+<div class="line">Arch Rock Corporation</div>
+<div class="line">657 Mission St. Ste 600</div>
+<div class="line">San Francisco, CA 94105-4120</div>
+<div class="line"><br /></div>
+<div class="line">phone - +1 415 692-0828 x2835</div>
</div>
</div>
<div class="section">
-<h1><a id="citations" name="citations">5. Citations</a></h1>
+<h1><a id="citations" name="citations">6. Citations</a></h1>
<table class="docutils citation" frame="void" id="tep113" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
projects / tinyos-2.x.git / blobdiff