git.gag.com Git - web/altusmetrum/blob - AltOS/doc/altos.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>AltOS</title><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="AltOS"><div class="titlepage"><div><div><h1 class="title"><a name="idm14830240"></a>AltOS</h1></div><div><h2 class="subtitle">Altos Metrum Operating System</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Keith</span> <span class="surname">Packard</span></h3></div></div><div><p class="copyright">Copyright © 2010 Keith Packard</p></div><div><div class="legalnotice" title="Legal Notice"><a name="idp1786584"></a><p>
   2         This document is released under the terms of the
   3         <a class="ulink" href="http://creativecommons.org/licenses/by-sa/3.0/" target="_top">
   4           Creative Commons ShareAlike 3.0
   5         </a>
   6         license.
   7       </p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 0.1</td><td align="left">22 November 2010</td></tr><tr><td align="left" colspan="2">Initial content</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#idp1007408">1. Overview</a></span></dt><dt><span class="chapter"><a href="#idp2570488">2. Programming the 8051 with SDCC</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3335368">1. 8051 memory spaces</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2345416">1.1. __data</a></span></dt><dt><span class="section"><a href="#idp1747472">1.2. __idata</a></span></dt><dt><span class="section"><a href="#idp2268896">1.3. __xdata</a></span></dt><dt><span class="section"><a href="#idp2450056">1.4. __pdata</a></span></dt><dt><span class="section"><a href="#idp1759568">1.5. __code</a></span></dt><dt><span class="section"><a href="#idp2412672">1.6. __bit</a></span></dt><dt><span class="section"><a href="#idp3063120">1.7. __sfr, __sfr16, __sfr32, __sbit</a></span></dt></dl></dd><dt><span class="section"><a href="#idp3035016">2. Function calls on the 8051</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3310384">2.1. __reentrant functions</a></span></dt><dt><span class="section"><a href="#idp2964320">2.2. Non __reentrant functions</a></span></dt><dt><span class="section"><a href="#idp1749176">2.3. __interrupt functions</a></span></dt><dt><span class="section"><a href="#idp2952984">2.4. __critical functions and statements</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#idp2996120">3. Task functions</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2706040">1. ao_add_task</a></span></dt><dt><span class="section"><a href="#idp2783376">2. ao_exit</a></span></dt><dt><span class="section"><a href="#idp3175128">3. ao_sleep</a></span></dt><dt><span class="section"><a href="#idp2128856">4. ao_wakeup</a></span></dt><dt><span class="section"><a href="#idp2171264">5. ao_alarm</a></span></dt><dt><span class="section"><a href="#idp1183336">6. ao_start_scheduler</a></span></dt><dt><span class="section"><a href="#idp3499216">7. ao_clock_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp3096472">4. Timer Functions</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3254408">1. ao_time</a></span></dt><dt><span class="section"><a href="#idp3394760">2. ao_delay</a></span></dt><dt><span class="section"><a href="#idp2275376">3. ao_timer_set_adc_interval</a></span></dt><dt><span class="section"><a href="#idp3123208">4. ao_timer_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp3220992">5. AltOS Mutexes</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2768696">1. ao_mutex_get</a></span></dt><dt><span class="section"><a href="#idp2986320">2. ao_mutex_put</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp2941440">6. CC1111 DMA engine</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3384272">1. ao_dma_alloc</a></span></dt><dt><span class="section"><a href="#idp2607448">2. ao_dma_set_transfer</a></span></dt><dt><span class="section"><a href="#idp2693856">3. ao_dma_start</a></span></dt><dt><span class="section"><a href="#idp3384000">4. ao_dma_trigger</a></span></dt><dt><span class="section"><a href="#idp1789224">5. ao_dma_abort</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp3413720">7. SDCC Stdio interface</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2822792">1. putchar</a></span></dt><dt><span class="section"><a href="#idp2195872">2. getchar</a></span></dt><dt><span class="section"><a href="#idp3467784">3. flush</a></span></dt><dt><span class="section"><a href="#idp2635624">4. ao_add_stdio</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp1974208">8. Command line interface</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2527728">1. ao_cmd_register</a></span></dt><dt><span class="section"><a href="#idp3042496">2. ao_cmd_lex</a></span></dt><dt><span class="section"><a href="#idp3394520">3. ao_cmd_put16</a></span></dt><dt><span class="section"><a href="#idp2319960">4. ao_cmd_put8</a></span></dt><dt><span class="section"><a href="#idp3139656">5. ao_cmd_white</a></span></dt><dt><span class="section"><a href="#idp3492136">6. ao_cmd_hex</a></span></dt><dt><span class="section"><a href="#idp2389576">7. ao_cmd_decimal</a></span></dt><dt><span class="section"><a href="#idp2185464">8. ao_match_word</a></span></dt><dt><span class="section"><a href="#idp2280648">9. ao_cmd_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp2495376">9. CC1111 USB target device</a></span></dt><dd><dl><dt><span class="section"><a href="#idp1747872">1. ao_usb_flush</a></span></dt><dt><span class="section"><a href="#idp2050352">2. ao_usb_putchar</a></span></dt><dt><span class="section"><a href="#idp2639304">3. ao_usb_pollchar</a></span></dt><dt><span class="section"><a href="#idp3533104">4. ao_usb_getchar</a></span></dt><dt><span class="section"><a href="#idp1750296">5. ao_usb_disable</a></span></dt><dt><span class="section"><a href="#idp2101016">6. ao_usb_enable</a></span></dt><dt><span class="section"><a href="#idp2678984">7. ao_usb_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp2249432">10. CC1111 Serial peripheral</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2996672">1. ao_serial_getchar</a></span></dt><dt><span class="section"><a href="#idp3155952">2. ao_serial_putchar</a></span></dt><dt><span class="section"><a href="#idp3350064">3. ao_serial_drain</a></span></dt><dt><span class="section"><a href="#idp2065008">4. ao_serial_set_speed</a></span></dt><dt><span class="section"><a href="#idp2450936">5. ao_serial_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp1286080">11. CC1111 Radio peripheral</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3302144">1. ao_radio_set_telemetry</a></span></dt><dt><span class="section"><a href="#idp988776">2. ao_radio_set_packet</a></span></dt><dt><span class="section"><a href="#idp3394248">3. ao_radio_set_rdf</a></span></dt><dt><span class="section"><a href="#idp3062848">4. ao_radio_idle</a></span></dt><dt><span class="section"><a href="#idp2490456">5. ao_radio_get</a></span></dt><dt><span class="section"><a href="#idp2147760">6. ao_radio_put</a></span></dt><dt><span class="section"><a href="#idp1214600">7. ao_radio_abort</a></span></dt><dt><span class="section"><a href="#idp1806960">8. ao_radio_send</a></span></dt><dt><span class="section"><a href="#idp3252216">9. ao_radio_recv</a></span></dt><dt><span class="section"><a href="#idp1259776">10. ao_radio_rdf</a></span></dt><dt><span class="section"><a href="#idp2069696">11. ao_packet_putchar</a></span></dt><dt><span class="section"><a href="#idp1536592">12. ao_packet_pollchar</a></span></dt><dt><span class="section"><a href="#idp3165392">13. ao_packet_slave_start</a></span></dt><dt><span class="section"><a href="#idp3384408">14. ao_packet_slave_stop</a></span></dt><dt><span class="section"><a href="#idp2784376">15. ao_packet_slave_init</a></span></dt><dt><span class="section"><a href="#idp2737784">16. ao_packet_master_init</a></span></dt></dl></dd></dl></div><div class="chapter" title="Chapter 1. Overview"><div class="titlepage"><div><div><h2 class="title"><a name="idp1007408"></a>Chapter 1. Overview</h2></div></div></div><p>
   8       AltOS is a operating system built for the 8051-compatible
   9       processor found in the TI cc1111 microcontroller. It's designed
  10       to be small and easy to program with. The main features are:
  11       </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Multi-tasking. While the 8051 doesn't provide separate
  12           address spaces, it's often easier to write code that operates
  13           in separate threads instead of tying everything into one giant
  14           event loop.
  15           </p></li><li class="listitem"><p>Non-preemptive. This increases latency for thread
  16           switching but reduces the number of places where context
  17           switching can occur. It also simplifies the operating system
  18           design somewhat. Nothing in the target system (rocket flight
  19           control) has tight timing requirements, and so this seems like
  20           a reasonable compromise.
  21           </p></li><li class="listitem"><p>Sleep/wakeup scheduling. Taken directly from ancient
  22           Unix designs, these two provide the fundemental scheduling
  23           primitive within AltOS.
  24           </p></li><li class="listitem"><p>Mutexes. As a locking primitive, mutexes are easier to
  25           use than semaphores, at least in my experience.
  26           </p></li><li class="listitem"><p>Timers. Tasks can set an alarm which will abort any
  27           pending sleep, allowing operations to time-out instead of
  28           blocking forever.
  29           </p></li></ul></div><p>
  30     </p><p>
  31       The device drivers and other subsystems in AltOS are
  32       conventionally enabled by invoking their _init() function from
  33       the 'main' function before that calls
  34       ao_start_scheduler(). These functions initialize the pin
  35       assignments, add various commands to the command processor and
  36       may add tasks to the scheduler to handle the device. A typical
  37       main program, thus, looks like:
  38       </p><pre class="programlisting">
  39         void
  40         main(void)
  41         {
  42                 ao_clock_init();
  43
  44                 /* Turn on the LED until the system is stable */
  45                 ao_led_init(LEDS_AVAILABLE);
  46                 ao_led_on(AO_LED_RED);
  47                 ao_timer_init();
  48                 ao_cmd_init();
  49                 ao_usb_init();
  50                 ao_monitor_init(AO_LED_GREEN, TRUE);
  51                 ao_rssi_init(AO_LED_RED);
  52                 ao_radio_init();
  53                 ao_packet_slave_init();
  54                 ao_packet_master_init();
  55                 #if HAS_DBG
  56                 ao_dbg_init();
  57                 #endif
  58                 ao_config_init();
  59                 ao_start_scheduler();
  60         }
  61       </pre><p>
  62       As you can see, a long sequence of subsystems are initialized
  63       and then the scheduler is started.
  64     </p></div><div class="chapter" title="Chapter 2. Programming the 8051 with SDCC"><div class="titlepage"><div><div><h2 class="title"><a name="idp2570488"></a>Chapter 2. Programming the 8051 with SDCC</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp3335368">1. 8051 memory spaces</a></span></dt><dd><dl><dt><span class="section"><a href="#idp2345416">1.1. __data</a></span></dt><dt><span class="section"><a href="#idp1747472">1.2. __idata</a></span></dt><dt><span class="section"><a href="#idp2268896">1.3. __xdata</a></span></dt><dt><span class="section"><a href="#idp2450056">1.4. __pdata</a></span></dt><dt><span class="section"><a href="#idp1759568">1.5. __code</a></span></dt><dt><span class="section"><a href="#idp2412672">1.6. __bit</a></span></dt><dt><span class="section"><a href="#idp3063120">1.7. __sfr, __sfr16, __sfr32, __sbit</a></span></dt></dl></dd><dt><span class="section"><a href="#idp3035016">2. Function calls on the 8051</a></span></dt><dd><dl><dt><span class="section"><a href="#idp3310384">2.1. __reentrant functions</a></span></dt><dt><span class="section"><a href="#idp2964320">2.2. Non __reentrant functions</a></span></dt><dt><span class="section"><a href="#idp1749176">2.3. __interrupt functions</a></span></dt><dt><span class="section"><a href="#idp2952984">2.4. __critical functions and statements</a></span></dt></dl></dd></dl></div><p>
  65       The 8051 is a primitive 8-bit processor, designed in the mists
  66       of time in as few transistors as possible. The architecture is
  67       highly irregular and includes several separate memory
  68       spaces. Furthermore, accessing stack variables is slow, and the
  69       stack itself is of limited size. While SDCC papers over the
  70       instruction set, it is not completely able to hide the memory
  71       architecture from the application designer.
  72     </p><div class="section" title="1. 8051 memory spaces"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3335368"></a>1. 8051 memory spaces</h2></div></div></div><p>
  73         The __data/__xdata/__code memory spaces below were completely
  74         separate in the original 8051 design. In the cc1111, this
  75         isn't true&#8212;they all live in a single unified 64kB address
  76         space, and so it's possible to convert any address into a
  77         unique 16-bit address. SDCC doesn't know this, and so a
  78         'global' address to SDCC consumes 3 bytes of memory, 1 byte as
  79         a tag indicating the memory space and 2 bytes of offset within
  80         that space. AltOS avoids these 3-byte addresses as much as
  81         possible; using them involves a function call per byte
  82         access. The result is that nearly every variable declaration
  83         is decorated with a memory space identifier which clutters the
  84         code but makes the resulting code far smaller and more
  85         efficient.
  86       </p><div class="section" title="1.1. __data"><div class="titlepage"><div><div><h3 class="title"><a name="idp2345416"></a>1.1. __data</h3></div></div></div><p>
  87           The 8051 can directly address these 128 bytes of
  88           memory. This makes them precious so they should be
  89           reserved for frequently addressed values. Oh, just to
  90           confuse things further, the 8 general registers in the
  91           CPU are actually stored in this memory space. There are
  92           magic instructions to 'bank switch' among 4 banks of
  93           these registers located at 0x00 - 0x1F. AltOS uses only
  94           the first bank at 0x00 - 0x07, leaving the other 24
  95           bytes available for other data.
  96         </p></div><div class="section" title="1.2. __idata"><div class="titlepage"><div><div><h3 class="title"><a name="idp1747472"></a>1.2. __idata</h3></div></div></div><p>
  97           There are an additional 128 bytes of internal memory
  98           that share the same address space as __data but which
  99           cannot be directly addressed. The stack normally
 100           occupies this space and so AltOS doesn't place any
 101           static storage here.
 102         </p></div><div class="section" title="1.3. __xdata"><div class="titlepage"><div><div><h3 class="title"><a name="idp2268896"></a>1.3. __xdata</h3></div></div></div><p>
 103           This is additional general memory accessed through a
 104           single 16-bit address register. The CC1111F32 has 32kB
 105           of memory available here. Most program data should live
 106           in this memory space.
 107         </p></div><div class="section" title="1.4. __pdata"><div class="titlepage"><div><div><h3 class="title"><a name="idp2450056"></a>1.4. __pdata</h3></div></div></div><p>
 108           This is an alias for the first 256 bytes of __xdata
 109           memory, but uses a shorter addressing mode with
 110           single global 8-bit value for the high 8 bits of the
 111           address and any of several 8-bit registers for the low 8
 112           bits. AltOS uses a few bits of this memory, it should
 113           probably use more.
 114         </p></div><div class="section" title="1.5. __code"><div class="titlepage"><div><div><h3 class="title"><a name="idp1759568"></a>1.5. __code</h3></div></div></div><p>
 115           All executable code must live in this address space, but
 116           you can stick read-only data here too. It is addressed
 117           using the 16-bit address register and special 'code'
 118           access opcodes. Anything read-only should live in this space.
 119         </p></div><div class="section" title="1.6. __bit"><div class="titlepage"><div><div><h3 class="title"><a name="idp2412672"></a>1.6. __bit</h3></div></div></div><p>
 120           The 8051 has 128 bits of bit-addressible memory that
 121           lives in the __data segment from 0x20 through
 122           0x2f. Special instructions access these bits
 123           in a single atomic operation. This isn't so much a
 124           separate address space as a special addressing mode for
 125           a few bytes in the __data segment.
 126         </p></div><div class="section" title="1.7. __sfr, __sfr16, __sfr32, __sbit"><div class="titlepage"><div><div><h3 class="title"><a name="idp3063120"></a>1.7. __sfr, __sfr16, __sfr32, __sbit</h3></div></div></div><p>
 127           Access to physical registers in the device use this mode
 128           which declares the variable name, it's type and the
 129           address it lives at. No memory is allocated for these
 130           variables.
 131         </p></div></div><div class="section" title="2. Function calls on the 8051"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3035016"></a>2. Function calls on the 8051</h2></div></div></div><p>
 132         Because stack addressing is expensive, and stack space
 133         limited, the default function call declaration in SDCC
 134         allocates all parameters and local variables in static global
 135         memory. Just like fortran. This makes these functions
 136         non-reentrant, and also consume space for parameters and
 137         locals even when they are not running. The benefit is smaller
 138         code and faster execution.
 139       </p><div class="section" title="2.1. __reentrant functions"><div class="titlepage"><div><div><h3 class="title"><a name="idp3310384"></a>2.1. __reentrant functions</h3></div></div></div><p>
 140           All functions which are re-entrant, either due to recursion
 141           or due to a potential context switch while executing, should
 142           be marked as __reentrant so that their parameters and local
 143           variables get allocated on the stack. This ensures that
 144           these values are not overwritten by another invocation of
 145           the function.
 146         </p><p>
 147           Functions which use significant amounts of space for
 148           arguments and/or local variables and which are not often
 149           invoked can also be marked as __reentrant. The resulting
 150           code will be larger, but the savings in memory are
 151           frequently worthwhile.
 152         </p></div><div class="section" title="2.2. Non __reentrant functions"><div class="titlepage"><div><div><h3 class="title"><a name="idp2964320"></a>2.2. Non __reentrant functions</h3></div></div></div><p>
 153           All parameters and locals in non-reentrant functions can
 154           have data space decoration so that they are allocated in
 155           __xdata, __pdata or __data space as desired. This can avoid
 156           consuming __data space for infrequently used variables in
 157           frequently used functions.
 158         </p><p>
 159           All library functions called by SDCC, including functions
 160           for multiplying and dividing large data types, are
 161           non-reentrant. Because of this, interrupt handlers must not
 162           invoke any library functions, including the multiply and
 163           divide code.
 164         </p></div><div class="section" title="2.3. __interrupt functions"><div class="titlepage"><div><div><h3 class="title"><a name="idp1749176"></a>2.3. __interrupt functions</h3></div></div></div><p>
 165           Interrupt functions are declared with with an __interrupt
 166           decoration that includes the interrupt number. SDCC saves
 167           and restores all of the registers in these functions and
 168           uses the 'reti' instruction at the end so that they operate
 169           as stand-alone interrupt handlers. Interrupt functions may
 170           call the ao_wakeup function to wake AltOS tasks.
 171         </p></div><div class="section" title="2.4. __critical functions and statements"><div class="titlepage"><div><div><h3 class="title"><a name="idp2952984"></a>2.4. __critical functions and statements</h3></div></div></div><p>
 172           SDCC has built-in support for suspending interrupts during
 173           critical code. Functions marked as __critical will have
 174           interrupts suspended for the whole period of
 175           execution. Individual statements may also be marked as
 176           __critical which blocks interrupts during the execution of
 177           that statement. Keeping critical sections as short as
 178           possible is key to ensuring that interrupts are handled as
 179           quickly as possible.
 180         </p></div></div></div><div class="chapter" title="Chapter 3. Task functions"><div class="titlepage"><div><div><h2 class="title"><a name="idp2996120"></a>Chapter 3. Task functions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2706040">1. ao_add_task</a></span></dt><dt><span class="section"><a href="#idp2783376">2. ao_exit</a></span></dt><dt><span class="section"><a href="#idp3175128">3. ao_sleep</a></span></dt><dt><span class="section"><a href="#idp2128856">4. ao_wakeup</a></span></dt><dt><span class="section"><a href="#idp2171264">5. ao_alarm</a></span></dt><dt><span class="section"><a href="#idp1183336">6. ao_start_scheduler</a></span></dt><dt><span class="section"><a href="#idp3499216">7. ao_clock_init</a></span></dt></dl></div><p>
 181       This chapter documents how to create, destroy and schedule AltOS tasks.
 182     </p><div class="section" title="1. ao_add_task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2706040"></a>1. ao_add_task</h2></div></div></div><pre class="programlisting">
 183         void
 184         ao_add_task(__xdata struct ao_task * task,
 185                     void (*start)(void),
 186                     __code char *name);
 187       </pre><p>
 188         This initializes the statically allocated task structure,
 189         assigns a name to it (not used for anything but the task
 190         display), and the start address. It does not switch to the
 191         new task. 'start' must not ever return; there is no place
 192         to return to.
 193       </p></div><div class="section" title="2. ao_exit"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2783376"></a>2. ao_exit</h2></div></div></div><pre class="programlisting">
 194         void
 195         ao_exit(void)
 196       </pre><p>
 197         This terminates the current task.
 198       </p></div><div class="section" title="3. ao_sleep"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3175128"></a>3. ao_sleep</h2></div></div></div><pre class="programlisting">
 199         void
 200         ao_sleep(__xdata void *wchan)
 201       </pre><p>
 202         This suspends the current task until 'wchan' is signaled
 203         by ao_wakeup, or until the timeout, set by ao_alarm,
 204         fires. If 'wchan' is signaled, ao_sleep returns 0, otherwise
 205         it returns 1. This is the only way to switch to another task.
 206       </p><p>
 207         Because ao_wakeup wakes every task waiting on a particular
 208         location, ao_sleep should be used in a loop that first
 209         checks the desired condition, blocks in ao_sleep and then
 210         rechecks until the condition is satisfied. If the
 211         location may be signaled from an interrupt handler, the
 212         code will need to block interrupts by using the __critical
 213         label around the block of code. Here's a complete example:
 214         </p><pre class="programlisting">
 215           __critical while (!ao_radio_done)
 216                   ao_sleep(&amp;ao_radio_done);
 217         </pre><p>
 218       </p></div><div class="section" title="4. ao_wakeup"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2128856"></a>4. ao_wakeup</h2></div></div></div><pre class="programlisting">
 219         void
 220         ao_wakeup(__xdata void *wchan)
 221       </pre><p>
 222         Wake all tasks blocked on 'wchan'. This makes them
 223         available to be run again, but does not actually switch
 224         to another task. Here's an example of using this:
 225         </p><pre class="programlisting">
 226           if (RFIF &amp; RFIF_IM_DONE) {
 227                   ao_radio_done = 1;
 228                   ao_wakeup(&amp;ao_radio_done);
 229                   RFIF &amp;= ~RFIF_IM_DONE;
 230           }
 231         </pre><p>
 232         Note that this need not be enclosed in __critical as the
 233         ao_sleep block can only be run from normal mode, and so
 234         this sequence can never be interrupted with execution of
 235         the other sequence.
 236       </p></div><div class="section" title="5. ao_alarm"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2171264"></a>5. ao_alarm</h2></div></div></div><pre class="programlisting">
 237         void
 238         ao_alarm(uint16_t delay)
 239       </pre><p>
 240         Schedules an alarm to fire in at least 'delay' ticks. If
 241         the task is asleep when the alarm fires, it will wakeup
 242         and ao_sleep will return 1.
 243         </p><pre class="programlisting">
 244           ao_alarm(ao_packet_master_delay);
 245           __critical while (!ao_radio_dma_done)
 246                   if (ao_sleep(&amp;ao_radio_dma_done) != 0)
 247                           ao_radio_abort();
 248         </pre><p>
 249         In this example, a timeout is set before waiting for
 250         incoming radio data. If no data is received before the
 251         timeout fires, ao_sleep will return 1 and then this code
 252         will abort the radio receive operation.
 253       </p></div><div class="section" title="6. ao_start_scheduler"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1183336"></a>6. ao_start_scheduler</h2></div></div></div><pre class="programlisting">
 254         void
 255         ao_start_scheduler(void)
 256       </pre><p>
 257         This is called from 'main' when the system is all
 258         initialized and ready to run. It will not return.
 259       </p></div><div class="section" title="7. ao_clock_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3499216"></a>7. ao_clock_init</h2></div></div></div><pre class="programlisting">
 260         void
 261         ao_clock_init(void)
 262       </pre><p>
 263         This turns on the external 48MHz clock then switches the
 264         hardware to using it. This is required by many of the
 265         internal devices like USB. It should be called by the
 266         'main' function first, before initializing any of the
 267         other devices in the system.
 268       </p></div></div><div class="chapter" title="Chapter 4. Timer Functions"><div class="titlepage"><div><div><h2 class="title"><a name="idp3096472"></a>Chapter 4. Timer Functions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp3254408">1. ao_time</a></span></dt><dt><span class="section"><a href="#idp3394760">2. ao_delay</a></span></dt><dt><span class="section"><a href="#idp2275376">3. ao_timer_set_adc_interval</a></span></dt><dt><span class="section"><a href="#idp3123208">4. ao_timer_init</a></span></dt></dl></div><p>
 269       AltOS sets up one of the cc1111 timers to run at 100Hz and
 270       exposes this tick as the fundemental unit of time. At each
 271       interrupt, AltOS increments the counter, and schedules any tasks
 272       waiting for that time to pass, then fires off the ADC system to
 273       collect current data readings. Doing this from the ISR ensures
 274       that the ADC values are sampled at a regular rate, independent
 275       of any scheduling jitter.
 276     </p><div class="section" title="1. ao_time"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3254408"></a>1. ao_time</h2></div></div></div><pre class="programlisting">
 277         uint16_t
 278         ao_time(void)
 279       </pre><p>
 280         Returns the current system tick count. Note that this is
 281         only a 16 bit value, and so it wraps every 655.36 seconds.
 282       </p></div><div class="section" title="2. ao_delay"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3394760"></a>2. ao_delay</h2></div></div></div><pre class="programlisting">
 283         void
 284         ao_delay(uint16_t ticks);
 285       </pre><p>
 286         Suspend the current task for at least 'ticks' clock units.
 287       </p></div><div class="section" title="3. ao_timer_set_adc_interval"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2275376"></a>3. ao_timer_set_adc_interval</h2></div></div></div><pre class="programlisting">
 288         void
 289         ao_timer_set_adc_interval(uint8_t interval);
 290       </pre><p>
 291         This sets the number of ticks between ADC samples. If set
 292         to 0, no ADC samples are generated. AltOS uses this to
 293         slow down the ADC sampling rate to save power.
 294       </p></div><div class="section" title="4. ao_timer_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3123208"></a>4. ao_timer_init</h2></div></div></div><pre class="programlisting">
 295         void
 296         ao_timer_init(void)
 297       </pre><p>
 298         This turns on the 100Hz tick using the CC1111 timer 1. It
 299         is required for any of the time-based functions to
 300         work. It should be called by 'main' before ao_start_scheduler.
 301       </p></div></div><div class="chapter" title="Chapter 5. AltOS Mutexes"><div class="titlepage"><div><div><h2 class="title"><a name="idp3220992"></a>Chapter 5. AltOS Mutexes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2768696">1. ao_mutex_get</a></span></dt><dt><span class="section"><a href="#idp2986320">2. ao_mutex_put</a></span></dt></dl></div><p>
 302       AltOS provides mutexes as a basic synchronization primitive. Each
 303       mutexes is simply a byte of memory which holds 0 when the mutex
 304       is free or the task id of the owning task when the mutex is
 305       owned. Mutex calls are checked&#8212;attempting to acquire a mutex
 306       already held by the current task or releasing a mutex not held
 307       by the current task will both cause a panic.
 308     </p><div class="section" title="1. ao_mutex_get"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2768696"></a>1. ao_mutex_get</h2></div></div></div><pre class="programlisting">
 309         void
 310         ao_mutex_get(__xdata uint8_t *mutex);
 311       </pre><p>
 312         Acquires the specified mutex, blocking if the mutex is
 313         owned by another task.
 314       </p></div><div class="section" title="2. ao_mutex_put"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2986320"></a>2. ao_mutex_put</h2></div></div></div><pre class="programlisting">
 315         void
 316         ao_mutex_put(__xdata uint8_t *mutex);
 317       </pre><p>
 318         Releases the specified mutex, waking up all tasks waiting
 319         for it.
 320       </p></div></div><div class="chapter" title="Chapter 6. CC1111 DMA engine"><div class="titlepage"><div><div><h2 class="title"><a name="idp2941440"></a>Chapter 6. CC1111 DMA engine</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp3384272">1. ao_dma_alloc</a></span></dt><dt><span class="section"><a href="#idp2607448">2. ao_dma_set_transfer</a></span></dt><dt><span class="section"><a href="#idp2693856">3. ao_dma_start</a></span></dt><dt><span class="section"><a href="#idp3384000">4. ao_dma_trigger</a></span></dt><dt><span class="section"><a href="#idp1789224">5. ao_dma_abort</a></span></dt></dl></div><p>
 321       The CC1111 contains a useful bit of extra hardware in the form
 322       of five programmable DMA engines. They can be configured to copy
 323       data in memory, or between memory and devices (or even between
 324       two devices). AltOS exposes a general interface to this hardware
 325       and uses it to handle radio and SPI data.
 326     </p><p>
 327       Code using a DMA engine should allocate one at startup
 328       time. There is no provision to free them, and if you run out,
 329       AltOS will simply panic.
 330     </p><p>
 331       During operation, the DMA engine is initialized with the
 332       transfer parameters. Then it is started, at which point it
 333       awaits a suitable event to start copying data. When copying data
 334       from hardware to memory, that trigger event is supplied by the
 335       hardware device. When copying data from memory to hardware, the
 336       transfer is usually initiated by software.
 337     </p><div class="section" title="1. ao_dma_alloc"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3384272"></a>1. ao_dma_alloc</h2></div></div></div><pre class="programlisting">
 338         uint8_t
 339         ao_dma_alloc(__xdata uint8_t *done)
 340       </pre><p>
 341         Allocates a DMA engine, returning the identifier. Whenever
 342         this DMA engine completes a transfer. 'done' is cleared
 343         when the DMA is started, and then receives the
 344         AO_DMA_DONE bit on a successful transfer or the
 345         AO_DMA_ABORTED bit if ao_dma_abort was called. Note that
 346         it is possible to get both bits if the transfer was
 347         aborted after it had finished.
 348       </p></div><div class="section" title="2. ao_dma_set_transfer"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2607448"></a>2. ao_dma_set_transfer</h2></div></div></div><pre class="programlisting">
 349         void
 350         ao_dma_set_transfer(uint8_t id,
 351                             void __xdata *srcaddr,
 352                             void __xdata *dstaddr,
 353                             uint16_t count,
 354                             uint8_t cfg0,
 355                             uint8_t cfg1)
 356       </pre><p>
 357         Initializes the specified dma engine to copy data
 358         from 'srcaddr' to 'dstaddr' for 'count' units. cfg0 and
 359         cfg1 are values directly out of the CC1111 documentation
 360         and tell the DMA engine what the transfer unit size,
 361         direction and step are.
 362       </p></div><div class="section" title="3. ao_dma_start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2693856"></a>3. ao_dma_start</h2></div></div></div><pre class="programlisting">
 363         void
 364         ao_dma_start(uint8_t id);
 365       </pre><p>
 366         Arm the specified DMA engine and await a signal from
 367         either hardware or software to start transferring data.
 368       </p></div><div class="section" title="4. ao_dma_trigger"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3384000"></a>4. ao_dma_trigger</h2></div></div></div><pre class="programlisting">
 369         void
 370         ao_dma_trigger(uint8_t id)
 371       </pre><p>
 372         Trigger the specified DMA engine to start copying data.
 373       </p></div><div class="section" title="5. ao_dma_abort"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1789224"></a>5. ao_dma_abort</h2></div></div></div><pre class="programlisting">
 374         void
 375         ao_dma_abort(uint8_t id)
 376       </pre><p>
 377         Terminate any in-progress DMA transation, marking its
 378         'done' variable with the AO_DMA_ABORTED bit.
 379       </p></div></div><div class="chapter" title="Chapter 7. SDCC Stdio interface"><div class="titlepage"><div><div><h2 class="title"><a name="idp3413720"></a>Chapter 7. SDCC Stdio interface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2822792">1. putchar</a></span></dt><dt><span class="section"><a href="#idp2195872">2. getchar</a></span></dt><dt><span class="section"><a href="#idp3467784">3. flush</a></span></dt><dt><span class="section"><a href="#idp2635624">4. ao_add_stdio</a></span></dt></dl></div><p>
 380       AltOS offers a stdio interface over both USB and the RF packet
 381       link. This provides for control of the device localy or
 382       remotely. This is hooked up to the stdio functions in SDCC by
 383       providing the standard putchar/getchar/flush functions. These
 384       automatically multiplex the two available communication
 385       channels; output is always delivered to the channel which
 386       provided the most recent input.
 387     </p><div class="section" title="1. putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2822792"></a>1. putchar</h2></div></div></div><pre class="programlisting">
 388         void
 389         putchar(char c)
 390       </pre><p>
 391         Delivers a single character to the current console
 392         device.
 393       </p></div><div class="section" title="2. getchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2195872"></a>2. getchar</h2></div></div></div><pre class="programlisting">
 394         char
 395         getchar(void)
 396       </pre><p>
 397         Reads a single character from any of the available
 398         console devices. The current console device is set to
 399         that which delivered this character. This blocks until
 400         a character is available.
 401       </p></div><div class="section" title="3. flush"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3467784"></a>3. flush</h2></div></div></div><pre class="programlisting">
 402         void
 403         flush(void)
 404       </pre><p>
 405         Flushes the current console device output buffer. Any
 406         pending characters will be delivered to the target device.
 407       xo          </p></div><div class="section" title="4. ao_add_stdio"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2635624"></a>4. ao_add_stdio</h2></div></div></div><pre class="programlisting">
 408         void
 409         ao_add_stdio(char (*pollchar)(void),
 410                            void (*putchar)(char),
 411                            void (*flush)(void))
 412       </pre><p>
 413         This adds another console device to the available
 414         list.
 415       </p><p>
 416         'pollchar' returns either an available character or
 417         AO_READ_AGAIN if none is available. Significantly, it does
 418         not block. The device driver must set 'ao_stdin_ready' to
 419         1 and call ao_wakeup(&amp;ao_stdin_ready) when it receives
 420         input to tell getchar that more data is available, at
 421         which point 'pollchar' will be called again.
 422       </p><p>
 423         'putchar' queues a character for output, flushing if the output buffer is
 424         full. It may block in this case.
 425       </p><p>
 426         'flush' forces the output buffer to be flushed. It may
 427         block until the buffer is delivered, but it is not
 428         required to do so.
 429       </p></div></div><div class="chapter" title="Chapter 8. Command line interface"><div class="titlepage"><div><div><h2 class="title"><a name="idp1974208"></a>Chapter 8. Command line interface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2527728">1. ao_cmd_register</a></span></dt><dt><span class="section"><a href="#idp3042496">2. ao_cmd_lex</a></span></dt><dt><span class="section"><a href="#idp3394520">3. ao_cmd_put16</a></span></dt><dt><span class="section"><a href="#idp2319960">4. ao_cmd_put8</a></span></dt><dt><span class="section"><a href="#idp3139656">5. ao_cmd_white</a></span></dt><dt><span class="section"><a href="#idp3492136">6. ao_cmd_hex</a></span></dt><dt><span class="section"><a href="#idp2389576">7. ao_cmd_decimal</a></span></dt><dt><span class="section"><a href="#idp2185464">8. ao_match_word</a></span></dt><dt><span class="section"><a href="#idp2280648">9. ao_cmd_init</a></span></dt></dl></div><p>
 430       AltOS includes a simple command line parser which is hooked up
 431       to the stdio interfaces permitting remote control of the device
 432       over USB or the RF link as desired. Each command uses a single
 433       character to invoke it, the remaining characters on the line are
 434       available as parameters to the command.
 435     </p><div class="section" title="1. ao_cmd_register"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2527728"></a>1. ao_cmd_register</h2></div></div></div><pre class="programlisting">
 436         void
 437         ao_cmd_register(__code struct ao_cmds *cmds)
 438       </pre><p>
 439         This registers a set of commands with the command
 440         parser. There is a fixed limit on the number of command
 441         sets, the system will panic if too many are registered.
 442         Each command is defined by a struct ao_cmds entry:
 443         </p><pre class="programlisting">
 444           struct ao_cmds {
 445                   char          cmd;
 446                   void          (*func)(void);
 447                   const char    *help;
 448           };
 449         </pre><p>
 450         'cmd' is the character naming the command. 'func' is the
 451         function to invoke and 'help' is a string displayed by the
 452         '?' command. Syntax errors found while executing 'func'
 453         should be indicated by modifying the global ao_cmd_status
 454         variable with one of the following values:
 455         </p><div class="variablelist"><dl><dt></dt><dd><p>
 456                 The command was parsed successfully. There is no
 457                 need to assign this value, it is the default.
 458               </p></dd><dt></dt><dd><p>
 459                 A token in the line was invalid, such as a number
 460                 containing invalid characters. The low-level
 461                 lexing functions already assign this value as needed.
 462               </p></dd><dt></dt><dd><p>
 463                 The command line is invalid for some reason other
 464                 than invalid tokens.
 465               </p></dd></dl></div><p>
 466       </p></div><div class="section" title="2. ao_cmd_lex"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3042496"></a>2. ao_cmd_lex</h2></div></div></div><pre class="programlisting">
 467         void
 468         ao_cmd_lex(void);
 469       </pre><p>
 470         This gets the next character out of the command line
 471         buffer and sticks it into ao_cmd_lex_c. At the end of the
 472         line, ao_cmd_lex_c will get a newline ('\n') character.
 473       </p></div><div class="section" title="3. ao_cmd_put16"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3394520"></a>3. ao_cmd_put16</h2></div></div></div><pre class="programlisting">
 474         void
 475         ao_cmd_put16(uint16_t v);
 476       </pre><p>
 477         Writes 'v' as four hexadecimal characters.
 478       </p></div><div class="section" title="4. ao_cmd_put8"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2319960"></a>4. ao_cmd_put8</h2></div></div></div><pre class="programlisting">
 479         void
 480         ao_cmd_put8(uint8_t v);
 481       </pre><p>
 482         Writes 'v' as two hexadecimal characters.
 483       </p></div><div class="section" title="5. ao_cmd_white"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3139656"></a>5. ao_cmd_white</h2></div></div></div><pre class="programlisting">
 484         void
 485         ao_cmd_white(void)
 486       </pre><p>
 487         This skips whitespace by calling ao_cmd_lex while
 488         ao_cmd_lex_c is either a space or tab. It does not skip
 489         any characters if ao_cmd_lex_c already non-white.
 490       </p></div><div class="section" title="6. ao_cmd_hex"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3492136"></a>6. ao_cmd_hex</h2></div></div></div><pre class="programlisting">
 491         void
 492         ao_cmd_hex(void)
 493       </pre><p>
 494         This reads a 16-bit hexadecimal value from the command
 495         line with optional leading whitespace. The resulting value
 496         is stored in ao_cmd_lex_i;
 497       </p></div><div class="section" title="7. ao_cmd_decimal"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2389576"></a>7. ao_cmd_decimal</h2></div></div></div><pre class="programlisting">
 498         void
 499         ao_cmd_decimal(void)
 500       </pre><p>
 501         This reads a 32-bit decimal value from the command
 502         line with optional leading whitespace. The resulting value
 503         is stored in ao_cmd_lex_u32 and the low 16 bits are stored
 504         in ao_cmd_lex_i;
 505       </p></div><div class="section" title="8. ao_match_word"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2185464"></a>8. ao_match_word</h2></div></div></div><pre class="programlisting">
 506         uint8_t
 507         ao_match_word(__code char *word)
 508       </pre><p>
 509         This checks to make sure that 'word' occurs on the command
 510         line. It does not skip leading white space. If 'word' is
 511         found, then 1 is returned. Otherwise, ao_cmd_status is set to
 512         ao_cmd_syntax_error and 0 is returned.
 513       </p></div><div class="section" title="9. ao_cmd_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2280648"></a>9. ao_cmd_init</h2></div></div></div><pre class="programlisting">
 514         void
 515         ao_cmd_init(void
 516       </pre><p>
 517         Initializes the command system, setting up the built-in
 518         commands and adding a task to run the command processing
 519         loop. It should be called by 'main' before ao_start_scheduler.
 520       </p></div></div><div class="chapter" title="Chapter 9. CC1111 USB target device"><div class="titlepage"><div><div><h2 class="title"><a name="idp2495376"></a>Chapter 9. CC1111 USB target device</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp1747872">1. ao_usb_flush</a></span></dt><dt><span class="section"><a href="#idp2050352">2. ao_usb_putchar</a></span></dt><dt><span class="section"><a href="#idp2639304">3. ao_usb_pollchar</a></span></dt><dt><span class="section"><a href="#idp3533104">4. ao_usb_getchar</a></span></dt><dt><span class="section"><a href="#idp1750296">5. ao_usb_disable</a></span></dt><dt><span class="section"><a href="#idp2101016">6. ao_usb_enable</a></span></dt><dt><span class="section"><a href="#idp2678984">7. ao_usb_init</a></span></dt></dl></div><p>
 521       The CC1111 contains a full-speed USB target device. It can be
 522       programmed to offer any kind of USB target, but to simplify
 523       interactions with a variety of operating systems, AltOS provides
 524       only a single target device profile, that of a USB modem which
 525       has native drivers for Linux, Windows and Mac OS X. It would be
 526       easy to change the code to provide an alternate target device if
 527       necessary.
 528     </p><p>
 529       To the rest of the system, the USB device looks like a simple
 530       two-way byte stream. It can be hooked into the command line
 531       interface if desired, offering control of the device over the
 532       USB link. Alternatively, the functions can be accessed directly
 533       to provide for USB-specific I/O.
 534     </p><div class="section" title="1. ao_usb_flush"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1747872"></a>1. ao_usb_flush</h2></div></div></div><pre class="programlisting">
 535         void
 536         ao_usb_flush(void);
 537       </pre><p>
 538         Flushes any pending USB output. This queues an 'IN' packet
 539         to be delivered to the USB host if there is pending data,
 540         or if the last IN packet was full to indicate to the host
 541         that there isn't any more pending data available.
 542       </p></div><div class="section" title="2. ao_usb_putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2050352"></a>2. ao_usb_putchar</h2></div></div></div><pre class="programlisting">
 543         void
 544         ao_usb_putchar(char c);
 545       </pre><p>
 546         If there is a pending 'IN' packet awaiting delivery to the
 547         host, this blocks until that has been fetched. Then, this
 548         adds a byte to the pending IN packet for delivery to the
 549         USB host. If the USB packet is full, this queues the 'IN'
 550         packet for delivery.
 551       </p></div><div class="section" title="3. ao_usb_pollchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2639304"></a>3. ao_usb_pollchar</h2></div></div></div><pre class="programlisting">
 552         char
 553         ao_usb_pollchar(void);
 554       </pre><p>
 555         If there are no characters remaining in the last 'OUT'
 556         packet received, this returns AO_READ_AGAIN. Otherwise, it
 557         returns the next character, reporting to the host that it
 558         is ready for more data when the last character is gone.
 559       </p></div><div class="section" title="4. ao_usb_getchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3533104"></a>4. ao_usb_getchar</h2></div></div></div><pre class="programlisting">
 560         char
 561         ao_usb_getchar(void);
 562       </pre><p>
 563         This uses ao_pollchar to receive the next character,
 564         blocking while ao_pollchar returns AO_READ_AGAIN.
 565       </p></div><div class="section" title="5. ao_usb_disable"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1750296"></a>5. ao_usb_disable</h2></div></div></div><pre class="programlisting">
 566         void
 567         ao_usb_disable(void);
 568       </pre><p>
 569         This turns off the USB controller. It will no longer
 570         respond to host requests, nor return characters. Calling
 571         any of the i/o routines while the USB device is disabled
 572         is undefined, and likely to break things. Disabling the
 573         USB device when not needed saves power.
 574       </p><p>
 575         Note that neither TeleDongle nor TeleMetrum are able to
 576         signal to the USB host that they have disconnected, so
 577         after disabling the USB device, it's likely that the cable
 578         will need to be disconnected and reconnected before it
 579         will work again.
 580       </p></div><div class="section" title="6. ao_usb_enable"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2101016"></a>6. ao_usb_enable</h2></div></div></div><pre class="programlisting">
 581         void
 582         ao_usb_enable(void);
 583       </pre><p>
 584         This turns the USB controller on again after it has been
 585         disabled. See the note above about needing to physically
 586         remove and re-insert the cable to get the host to
 587         re-initialize the USB link.
 588       </p></div><div class="section" title="7. ao_usb_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2678984"></a>7. ao_usb_init</h2></div></div></div><pre class="programlisting">
 589         void
 590         ao_usb_init(void);
 591       </pre><p>
 592         This turns the USB controller on, adds a task to handle
 593         the control end point and adds the usb I/O functions to
 594         the stdio system. Call this from main before
 595         ao_start_scheduler.
 596       </p></div></div><div class="chapter" title="Chapter 10. CC1111 Serial peripheral"><div class="titlepage"><div><div><h2 class="title"><a name="idp2249432"></a>Chapter 10. CC1111 Serial peripheral</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp2996672">1. ao_serial_getchar</a></span></dt><dt><span class="section"><a href="#idp3155952">2. ao_serial_putchar</a></span></dt><dt><span class="section"><a href="#idp3350064">3. ao_serial_drain</a></span></dt><dt><span class="section"><a href="#idp2065008">4. ao_serial_set_speed</a></span></dt><dt><span class="section"><a href="#idp2450936">5. ao_serial_init</a></span></dt></dl></div><p>
 597       The CC1111 provides two USART peripherals. AltOS uses one for
 598       asynch serial data, generally to communicate with a GPS device,
 599       and the other for a SPI bus. The UART is configured to operate
 600       in 8-bits, no parity, 1 stop bit framing. The default
 601       configuration has clock settings for 4800, 9600 and 57600 baud
 602       operation. Additional speeds can be added by computing
 603       appropriate clock values.
 604     </p><p>
 605       To prevent loss of data, AltOS provides receive and transmit
 606       fifos of 32 characters each.
 607     </p><div class="section" title="1. ao_serial_getchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2996672"></a>1. ao_serial_getchar</h2></div></div></div><pre class="programlisting">
 608         char
 609         ao_serial_getchar(void);
 610       </pre><p>
 611         Returns the next character from the receive fifo, blocking
 612         until a character is received if the fifo is empty.
 613       </p></div><div class="section" title="2. ao_serial_putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3155952"></a>2. ao_serial_putchar</h2></div></div></div><pre class="programlisting">
 614         void
 615         ao_serial_putchar(char c);
 616       </pre><p>
 617         Adds a character to the transmit fifo, blocking if the
 618         fifo is full. Starts transmitting characters.
 619       </p></div><div class="section" title="3. ao_serial_drain"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3350064"></a>3. ao_serial_drain</h2></div></div></div><pre class="programlisting">
 620         void
 621         ao_serial_drain(void);
 622       </pre><p>
 623         Blocks until the transmit fifo is empty. Used internally
 624         when changing serial speeds.
 625       </p></div><div class="section" title="4. ao_serial_set_speed"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2065008"></a>4. ao_serial_set_speed</h2></div></div></div><pre class="programlisting">
 626         void
 627         ao_serial_set_speed(uint8_t speed);
 628       </pre><p>
 629         Changes the serial baud rate to one of
 630         AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or
 631         AO_SERIAL_SPEED_57600. This first flushes the transmit
 632         fifo using ao_serial_drain.
 633       </p></div><div class="section" title="5. ao_serial_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2450936"></a>5. ao_serial_init</h2></div></div></div><pre class="programlisting">
 634         void
 635         ao_serial_init(void)
 636       </pre><p>
 637         Initializes the serial peripheral. Call this from 'main'
 638         before jumping to ao_start_scheduler. The default speed
 639         setting is AO_SERIAL_SPEED_4800.
 640       </p></div></div><div class="chapter" title="Chapter 11. CC1111 Radio peripheral"><div class="titlepage"><div><div><h2 class="title"><a name="idp1286080"></a>Chapter 11. CC1111 Radio peripheral</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#idp3302144">1. ao_radio_set_telemetry</a></span></dt><dt><span class="section"><a href="#idp988776">2. ao_radio_set_packet</a></span></dt><dt><span class="section"><a href="#idp3394248">3. ao_radio_set_rdf</a></span></dt><dt><span class="section"><a href="#idp3062848">4. ao_radio_idle</a></span></dt><dt><span class="section"><a href="#idp2490456">5. ao_radio_get</a></span></dt><dt><span class="section"><a href="#idp2147760">6. ao_radio_put</a></span></dt><dt><span class="section"><a href="#idp1214600">7. ao_radio_abort</a></span></dt><dt><span class="section"><a href="#idp1806960">8. ao_radio_send</a></span></dt><dt><span class="section"><a href="#idp3252216">9. ao_radio_recv</a></span></dt><dt><span class="section"><a href="#idp1259776">10. ao_radio_rdf</a></span></dt><dt><span class="section"><a href="#idp2069696">11. ao_packet_putchar</a></span></dt><dt><span class="section"><a href="#idp1536592">12. ao_packet_pollchar</a></span></dt><dt><span class="section"><a href="#idp3165392">13. ao_packet_slave_start</a></span></dt><dt><span class="section"><a href="#idp3384408">14. ao_packet_slave_stop</a></span></dt><dt><span class="section"><a href="#idp2784376">15. ao_packet_slave_init</a></span></dt><dt><span class="section"><a href="#idp2737784">16. ao_packet_master_init</a></span></dt></dl></div><p>
 641       The CC1111 radio transceiver sends and receives digital packets
 642       with forward error correction and detection. The AltOS driver is
 643       fairly specific to the needs of the TeleMetrum and TeleDongle
 644       devices, using it for other tasks may require customization of
 645       the driver itself. There are three basic modes of operation:
 646       </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
 647             Telemetry mode. In this mode, TeleMetrum transmits telemetry
 648             frames at a fixed rate. The frames are of fixed size. This
 649             is strictly a one-way communication from TeleMetrum to
 650             TeleDongle.
 651           </p></li><li class="listitem"><p>
 652             Packet mode. In this mode, the radio is used to create a
 653             reliable duplex byte stream between TeleDongle and
 654             TeleMetrum. This is an asymmetrical protocol with
 655             TeleMetrum only transmitting in response to a packet sent
 656             from TeleDongle. Thus getting data from TeleMetrum to
 657             TeleDongle requires polling. The polling rate is adaptive,
 658             when no data has been received for a while, the rate slows
 659             down. The packets are checked at both ends and invalid
 660             data are ignored.
 661           </p><p>
 662             On the TeleMetrum side, the packet link is hooked into the
 663             stdio mechanism, providing an alternate data path for the
 664             command processor. It is enabled when the unit boots up in
 665             'idle' mode.
 666           </p><p>
 667             On the TeleDongle side, the packet link is enabled with a
 668             command; data from the stdio package is forwarded over the
 669             packet link providing a connection from the USB command
 670             stream to the remote TeleMetrum device.
 671           </p></li><li class="listitem"><p>
 672             Radio Direction Finding mode. In this mode, TeleMetrum
 673             constructs a special packet that sounds like an audio tone
 674             when received by a conventional narrow-band FM
 675             receiver. This is designed to provide a beacon to track
 676             the device when other location mechanisms fail.
 677           </p></li></ol></div><p>
 678     </p><div class="section" title="1. ao_radio_set_telemetry"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3302144"></a>1. ao_radio_set_telemetry</h2></div></div></div><pre class="programlisting">
 679           void
 680           ao_radio_set_telemetry(void);
 681         </pre><p>
 682           Configures the radio to send or receive telemetry
 683           packets. This includes packet length, modulation scheme and
 684           other RF parameters. It does not include the base frequency
 685           or channel though. Those are set at the time of transmission
 686           or reception, in case the values are changed by the user.
 687         </p></div><div class="section" title="2. ao_radio_set_packet"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp988776"></a>2. ao_radio_set_packet</h2></div></div></div><pre class="programlisting">
 688           void
 689           ao_radio_set_packet(void);
 690         </pre><p>
 691           Configures the radio to send or receive packet data.  This
 692           includes packet length, modulation scheme and other RF
 693           parameters. It does not include the base frequency or
 694           channel though. Those are set at the time of transmission or
 695           reception, in case the values are changed by the user.
 696         </p></div><div class="section" title="3. ao_radio_set_rdf"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3394248"></a>3. ao_radio_set_rdf</h2></div></div></div><pre class="programlisting">
 697           void
 698           ao_radio_set_rdf(void);
 699         </pre><p>
 700           Configures the radio to send RDF 'packets'. An RDF 'packet'
 701           is a sequence of hex 0x55 bytes sent at a base bit rate of
 702           2kbps using a 5kHz deviation. All of the error correction
 703           and data whitening logic is turned off so that the resulting
 704           modulation is received as a 1kHz tone by a conventional 70cm
 705           FM audio receiver.
 706         </p></div><div class="section" title="4. ao_radio_idle"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3062848"></a>4. ao_radio_idle</h2></div></div></div><pre class="programlisting">
 707           void
 708           ao_radio_idle(void);
 709         </pre><p>
 710           Sets the radio device to idle mode, waiting until it reaches
 711           that state. This will terminate any in-progress transmit or
 712           receive operation.
 713         </p></div><div class="section" title="5. ao_radio_get"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2490456"></a>5. ao_radio_get</h2></div></div></div><pre class="programlisting">
 714           void
 715           ao_radio_get(void);
 716         </pre><p>
 717           Acquires the radio mutex and then configures the radio
 718           frequency using the global radio calibration and channel
 719           values.
 720         </p></div><div class="section" title="6. ao_radio_put"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2147760"></a>6. ao_radio_put</h2></div></div></div><pre class="programlisting">
 721           void
 722           ao_radio_put(void);
 723         </pre><p>
 724           Releases the radio mutex.
 725         </p></div><div class="section" title="7. ao_radio_abort"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1214600"></a>7. ao_radio_abort</h2></div></div></div><pre class="programlisting">
 726           void
 727           ao_radio_abort(void);
 728         </pre><p>
 729           Aborts any transmission or reception process by aborting the
 730           associated DMA object and calling ao_radio_idle to terminate
 731           the radio operation.
 732         </p></div><p>
 733       In telemetry mode, you can send or receive a telemetry
 734       packet. The data from receiving a packet also includes the RSSI
 735       and status values supplied by the receiver. These are added
 736       after the telemetry data.
 737     </p><div class="section" title="8. ao_radio_send"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1806960"></a>8. ao_radio_send</h2></div></div></div><pre class="programlisting">
 738           void
 739           ao_radio_send(__xdata struct ao_telemetry *telemetry);
 740         </pre><p>
 741           This sends the specific telemetry packet, waiting for the
 742           transmission to complete. The radio must have been set to
 743           telemetry mode. This function calls ao_radio_get() before
 744           sending, and ao_radio_put() afterwards, to correctly
 745           serialize access to the radio device.
 746         </p></div><div class="section" title="9. ao_radio_recv"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3252216"></a>9. ao_radio_recv</h2></div></div></div><pre class="programlisting">
 747           void
 748           ao_radio_recv(__xdata struct ao_radio_recv *radio);
 749         </pre><p>
 750           This blocks waiting for a telemetry packet to be received.
 751           The radio must have been set to telemetry mode. This
 752           function calls ao_radio_get() before receiving, and
 753           ao_radio_put() afterwards, to correctly serialize access
 754           to the radio device. This returns non-zero if a packet was
 755           received, or zero if the operation was aborted (from some
 756           other task calling ao_radio_abort()).
 757         </p></div><p>
 758       In radio direction finding mode, there's just one function to
 759       use
 760     </p><div class="section" title="10. ao_radio_rdf"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1259776"></a>10. ao_radio_rdf</h2></div></div></div><pre class="programlisting">
 761           void
 762           ao_radio_rdf(int ms);
 763         </pre><p>
 764           This sends an RDF packet lasting for the specified amount
 765           of time. The maximum length is 1020 ms.
 766         </p></div><p>
 767       Packet mode is asymmetrical and is configured at compile time
 768       for either master or slave mode (but not both). The basic I/O
 769       functions look the same at both ends, but the internals are
 770       different, along with the initialization steps.
 771     </p><div class="section" title="11. ao_packet_putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2069696"></a>11. ao_packet_putchar</h2></div></div></div><pre class="programlisting">
 772           void
 773           ao_packet_putchar(char c);
 774         </pre><p>
 775           If the output queue is full, this first blocks waiting for
 776           that data to be delivered. Then, queues a character for
 777           packet transmission. On the master side, this will
 778           transmit a packet if the output buffer is full. On the
 779           slave side, any pending data will be sent the next time
 780           the master polls for data.
 781         </p></div><div class="section" title="12. ao_packet_pollchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1536592"></a>12. ao_packet_pollchar</h2></div></div></div><pre class="programlisting">
 782           char
 783           ao_packet_pollchar(void);
 784         </pre><p>
 785           This returns a pending input character if available,
 786           otherwise returns AO_READ_AGAIN. On the master side, if
 787           this empties the buffer, it triggers a poll for more data.
 788         </p></div><div class="section" title="13. ao_packet_slave_start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3165392"></a>13. ao_packet_slave_start</h2></div></div></div><pre class="programlisting">
 789           void
 790           ao_packet_slave_start(void);
 791         </pre><p>
 792           This is available only on the slave side and starts a task
 793           to listen for packet data.
 794         </p></div><div class="section" title="14. ao_packet_slave_stop"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp3384408"></a>14. ao_packet_slave_stop</h2></div></div></div><pre class="programlisting">
 795           void
 796           ao_packet_slave_stop(void);
 797         </pre><p>
 798           Disables the packet slave task, stopping the radio receiver.
 799         </p></div><div class="section" title="15. ao_packet_slave_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2784376"></a>15. ao_packet_slave_init</h2></div></div></div><pre class="programlisting">
 800           void
 801           ao_packet_slave_init(void);
 802         </pre><p>
 803           Adds the packet stdio functions to the stdio package so
 804           that when packet slave mode is enabled, characters will
 805           get send and received through the stdio functions.
 806         </p></div><div class="section" title="16. ao_packet_master_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp2737784"></a>16. ao_packet_master_init</h2></div></div></div><pre class="programlisting">
 807           void
 808           ao_packet_master_init(void);
 809         </pre><p>
 810           Adds the 'p' packet forward command to start packet mode.
 811         </p></div></div></div></body></html>