1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>AltOS</title><link rel="stylesheet" type="text/css" href="am.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /></head><body><div xml:lang="en" class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a id="idm1"></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><code class="email"><<a class="email" href="mailto:keithp@keithp.com">keithp@keithp.com</a>></code></div></div><div><p class="copyright">Copyright © 2012 Keith Packard</p></div><div><div class="legalnotice"><a id="idm13"></a><p>
3 This document is released under the terms of the
4 <a class="ulink" href="http://creativecommons.org/licenses/by-sa/3.0/" target="_top">
5 Creative Commons ShareAlike 3.0
8 </p></div></div><div><a href="altos-revhistory.html">Revision History</a></div></div><hr /></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="chapter"><a href="#_overview">1. Overview</a></span></dt><dt><span class="chapter"><a href="#_altos_porting_layer">2. AltOS Porting Layer</a></span></dt><dd><dl><dt><span class="section"><a href="#_low_level_cpu_operations">2.1. Low-level CPU operations</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_arch_block_interrupts_ao_arch_release_interrupts">2.1.1. ao_arch_block_interrupts/ao_arch_release_interrupts</a></span></dt><dt><span class="section"><a href="#_ao_arch_save_regs_ao_arch_save_stack_ao_arch_restore_stack">2.1.2. ao_arch_save_regs, ao_arch_save_stack, ao_arch_restore_stack</a></span></dt><dt><span class="section"><a href="#_ao_arch_wait_interupt">2.1.3. ao_arch_wait_interupt</a></span></dt></dl></dd><dt><span class="section"><a href="#_gpio_operations">2.2. GPIO operations</a></span></dt><dd><dl><dt><span class="section"><a href="#_gpio_setup">2.2.1. GPIO setup</a></span></dt><dt><span class="section"><a href="#_reading_and_writing_gpio_pins">2.2.2. Reading and writing GPIO pins</a></span></dt></dl></dd><dt><span class="section"><a href="#_8051_memory_spaces">2.3. 8051 memory spaces</a></span></dt><dd><dl><dt><span class="section"><a href="#_data">2.3.1. __data</a></span></dt><dt><span class="section"><a href="#_idata">2.3.2. __idata</a></span></dt><dt><span class="section"><a href="#_xdata">2.3.3. __xdata</a></span></dt><dt><span class="section"><a href="#_pdata">2.3.4. __pdata</a></span></dt><dt><span class="section"><a href="#_code">2.3.5. __code</a></span></dt><dt><span class="section"><a href="#_bit">2.3.6. __bit</a></span></dt><dt><span class="section"><a href="#_emphasis_sfr_emphasis_sfr16_emphasis_sfr32_emphasis_sbit">2.3.7. <span class="emphasis"><em>sfr, </em></span>sfr16, <span class="emphasis"><em>sfr32, </em></span>sbit</a></span></dt></dl></dd><dt><span class="section"><a href="#_function_calls_on_the_8051">2.4. Function calls on the 8051</a></span></dt><dd><dl><dt><span class="section"><a href="#_reentrant_functions">2.4.1. __reentrant functions</a></span></dt><dt><span class="section"><a href="#_non___reentrant_functions">2.4.2. Non __reentrant functions</a></span></dt><dt><span class="section"><a href="#_interrupt_functions">2.4.3. __interrupt functions</a></span></dt><dt><span class="section"><a href="#_critical_functions_and_statements">2.4.4. __critical functions and statements</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_task_functions">3. Task functions</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_add_task">3.1. ao_add_task</a></span></dt><dt><span class="section"><a href="#_ao_exit">3.2. ao_exit</a></span></dt><dt><span class="section"><a href="#_ao_sleep">3.3. ao_sleep</a></span></dt><dt><span class="section"><a href="#_ao_wakeup">3.4. ao_wakeup</a></span></dt><dt><span class="section"><a href="#_ao_alarm">3.5. ao_alarm</a></span></dt><dt><span class="section"><a href="#_ao_start_scheduler">3.6. ao_start_scheduler</a></span></dt><dt><span class="section"><a href="#_ao_clock_init">3.7. ao_clock_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_timer_functions">4. Timer Functions</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_time">4.1. ao_time</a></span></dt><dt><span class="section"><a href="#_ao_delay">4.2. ao_delay</a></span></dt><dt><span class="section"><a href="#_ao_timer_set_adc_interval">4.3. ao_timer_set_adc_interval</a></span></dt><dt><span class="section"><a href="#_ao_timer_init">4.4. ao_timer_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_altos_mutexes">5. AltOS Mutexes</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_mutex_get">5.1. ao_mutex_get</a></span></dt><dt><span class="section"><a href="#_ao_mutex_put">5.2. ao_mutex_put</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_dma_engine">6. DMA engine</a></span></dt><dd><dl><dt><span class="section"><a href="#_cc1111_dma_engine">6.1. CC1111 DMA Engine</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_dma_alloc">6.1.1. ao_dma_alloc</a></span></dt><dt><span class="section"><a href="#_ao_dma_set_transfer">6.1.2. ao_dma_set_transfer</a></span></dt><dt><span class="section"><a href="#_ao_dma_start">6.1.3. ao_dma_start</a></span></dt><dt><span class="section"><a href="#_ao_dma_trigger">6.1.4. ao_dma_trigger</a></span></dt><dt><span class="section"><a href="#_ao_dma_abort">6.1.5. ao_dma_abort</a></span></dt></dl></dd><dt><span class="section"><a href="#_stm32l_dma_engine">6.2. STM32L DMA Engine</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_dma_alloc_2">6.2.1. ao_dma_alloc</a></span></dt><dt><span class="section"><a href="#_ao_dma_set_transfer_2">6.2.2. ao_dma_set_transfer</a></span></dt><dt><span class="section"><a href="#_ao_dma_set_isr">6.2.3. ao_dma_set_isr</a></span></dt><dt><span class="section"><a href="#_ao_dma_start_2">6.2.4. ao_dma_start</a></span></dt><dt><span class="section"><a href="#_ao_dma_done_transfer">6.2.5. ao_dma_done_transfer</a></span></dt><dt><span class="section"><a href="#_ao_dma_abort_2">6.2.6. ao_dma_abort</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#_stdio_interface">7. Stdio interface</a></span></dt><dd><dl><dt><span class="section"><a href="#_putchar">7.1. putchar</a></span></dt><dt><span class="section"><a href="#_getchar">7.2. getchar</a></span></dt><dt><span class="section"><a href="#_flush">7.3. flush</a></span></dt><dt><span class="section"><a href="#_ao_add_stdio">7.4. ao_add_stdio</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_command_line_interface">8. Command line interface</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_cmd_register">8.1. ao_cmd_register</a></span></dt><dt><span class="section"><a href="#_ao_cmd_lex">8.2. ao_cmd_lex</a></span></dt><dt><span class="section"><a href="#_ao_cmd_put16">8.3. ao_cmd_put16</a></span></dt><dt><span class="section"><a href="#_ao_cmd_put8">8.4. ao_cmd_put8</a></span></dt><dt><span class="section"><a href="#_ao_cmd_white">8.5. ao_cmd_white</a></span></dt><dt><span class="section"><a href="#_ao_cmd_hex">8.6. ao_cmd_hex</a></span></dt><dt><span class="section"><a href="#_ao_cmd_decimal">8.7. ao_cmd_decimal</a></span></dt><dt><span class="section"><a href="#_ao_match_word">8.8. ao_match_word</a></span></dt><dt><span class="section"><a href="#_ao_cmd_init">8.9. ao_cmd_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_usb_target_device">9. USB target device</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_usb_flush">9.1. ao_usb_flush</a></span></dt><dt><span class="section"><a href="#_ao_usb_putchar">9.2. ao_usb_putchar</a></span></dt><dt><span class="section"><a href="#_ao_usb_pollchar">9.3. ao_usb_pollchar</a></span></dt><dt><span class="section"><a href="#_ao_usb_getchar">9.4. ao_usb_getchar</a></span></dt><dt><span class="section"><a href="#_ao_usb_disable">9.5. ao_usb_disable</a></span></dt><dt><span class="section"><a href="#_ao_usb_enable">9.6. ao_usb_enable</a></span></dt><dt><span class="section"><a href="#_ao_usb_init">9.7. ao_usb_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_serial_peripherals">10. Serial peripherals</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_serial_getchar">10.1. ao_serial_getchar</a></span></dt><dt><span class="section"><a href="#_ao_serial_putchar">10.2. ao_serial_putchar</a></span></dt><dt><span class="section"><a href="#_ao_serial_drain">10.3. ao_serial_drain</a></span></dt><dt><span class="section"><a href="#_ao_serial_set_speed">10.4. ao_serial_set_speed</a></span></dt><dt><span class="section"><a href="#_ao_serial_init">10.5. ao_serial_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#_cc1111_cc1120_cc1200_radio_peripheral">11. CC1111/CC1120/CC1200 Radio peripheral</a></span></dt><dd><dl><dt><span class="section"><a href="#_radio_introduction">11.1. Radio Introduction</a></span></dt><dt><span class="section"><a href="#_ao_radio_set_telemetry">11.2. ao_radio_set_telemetry</a></span></dt><dt><span class="section"><a href="#_ao_radio_set_packet">11.3. ao_radio_set_packet</a></span></dt><dt><span class="section"><a href="#_ao_radio_set_rdf">11.4. ao_radio_set_rdf</a></span></dt><dt><span class="section"><a href="#_ao_radio_idle">11.5. ao_radio_idle</a></span></dt><dt><span class="section"><a href="#_ao_radio_get">11.6. ao_radio_get</a></span></dt><dt><span class="section"><a href="#_ao_radio_put">11.7. ao_radio_put</a></span></dt><dt><span class="section"><a href="#_ao_radio_abort">11.8. ao_radio_abort</a></span></dt><dt><span class="section"><a href="#_radio_telemetry">11.9. Radio Telemetry</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_radio_send">11.9.1. ao_radio_send</a></span></dt><dt><span class="section"><a href="#_ao_radio_recv">11.9.2. ao_radio_recv</a></span></dt></dl></dd><dt><span class="section"><a href="#_radio_direction_finding">11.10. Radio Direction Finding</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_radio_rdf">11.10.1. ao_radio_rdf</a></span></dt></dl></dd><dt><span class="section"><a href="#_radio_packet_mode">11.11. Radio Packet Mode</a></span></dt><dd><dl><dt><span class="section"><a href="#_ao_packet_putchar">11.11.1. ao_packet_putchar</a></span></dt><dt><span class="section"><a href="#_ao_packet_pollchar">11.11.2. ao_packet_pollchar</a></span></dt><dt><span class="section"><a href="#_ao_packet_slave_start">11.11.3. ao_packet_slave_start</a></span></dt><dt><span class="section"><a href="#_ao_packet_slave_stop">11.11.4. ao_packet_slave_stop</a></span></dt><dt><span class="section"><a href="#_ao_packet_slave_init">11.11.5. ao_packet_slave_init</a></span></dt><dt><span class="section"><a href="#_ao_packet_master_init">11.11.6. ao_packet_master_init</a></span></dt></dl></dd></dl></dd></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_overview"></a>Chapter 1. Overview</h1></div></div></div><p>AltOS is a operating system built for a variety of
9 microcontrollers used in Altus Metrum devices. It has a simple
10 porting layer for each CPU while providing a convenient
11 operating enviroment for the developer. AltOS currently
12 supports three different CPUs:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
13 STM32L series from ST Microelectronics. This ARM Cortex-M3
14 based microcontroller offers low power consumption and a
15 wide variety of built-in peripherals. Altus Metrum uses this
16 in the TeleMega, MegaDongle and TeleLCO projects.
17 </li><li class="listitem">
18 CC1111 from Texas Instruments. This device includes a
19 fabulous 10mW digital RF transceiver along with an
20 8051-compatible processor core and a range of
21 peripherals. This is used in the TeleMetrum, TeleMini,
22 TeleDongle and TeleFire projects which share the need for a
23 small microcontroller and an RF interface.
24 </li><li class="listitem">
25 ATmega32U4 from Atmel. This 8-bit AVR microcontroller is one
26 of the many used to create Arduino boards. The 32U4 includes
27 a USB interface, making it easy to connect to other
28 computers. Altus Metrum used this in prototypes of the
29 TeleScience and TelePyro boards; those have been switched to
30 the STM32L which is more capable and cheaper.
31 </li></ul></div><p>Among the features of AltOS are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
32 Multi-tasking. While microcontrollers often don’t
33 provide separate address spaces, it’s often easier to write
34 code that operates in separate threads instead of tying
35 everything into one giant event loop.
36 </li><li class="listitem">
37 Non-preemptive. This increases latency for thread
38 switching but reduces the number of places where context
39 switching can occur. It also simplifies the operating system
40 design somewhat. Nothing in the target system (rocket flight
41 control) has tight timing requirements, and so this seems like
42 a reasonable compromise.
43 </li><li class="listitem">
44 Sleep/wakeup scheduling. Taken directly from ancient
45 Unix designs, these two provide the fundemental scheduling
46 primitive within AltOS.
47 </li><li class="listitem">
48 Mutexes. As a locking primitive, mutexes are easier to
49 use than semaphores, at least in my experience.
50 </li><li class="listitem">
51 Timers. Tasks can set an alarm which will abort any
52 pending sleep, allowing operations to time-out instead of
54 </li></ul></div><p>The device drivers and other subsystems in AltOS are
55 conventionally enabled by invoking their _init() function from
56 the <span class="emphasis"><em>main</em></span> function before that calls
57 ao_start_scheduler(). These functions initialize the pin
58 assignments, add various commands to the command processor and
59 may add tasks to the scheduler to handle the device. A typical
60 main program, thus, looks like:</p><pre class="literallayout">void
65 /* Turn on the LED until the system is stable */
66 ao_led_init(LEDS_AVAILABLE);
67 ao_led_on(AO_LED_RED);
71 ao_monitor_init(AO_LED_GREEN, TRUE);
72 ao_rssi_init(AO_LED_RED);
74 ao_packet_slave_init();
75 ao_packet_master_init();
81 }</pre><p>As you can see, a long sequence of subsystems are initialized
82 and then the scheduler is started.</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_altos_porting_layer"></a>Chapter 2. AltOS Porting Layer</h1></div></div></div><p>AltOS provides a CPU-independent interface to various common
83 microcontroller subsystems, including GPIO pins, interrupts,
84 SPI, I2C, USB and asynchronous serial interfaces. By making
85 these CPU-independent, device drivers, generic OS and
86 application code can all be written that work on any supported
87 CPU. Many of the architecture abstraction interfaces are
88 prefixed with ao_arch.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_low_level_cpu_operations"></a>2.1. Low-level CPU operations</h2></div></div></div><p>These primitive operations provide the abstraction needed to
89 run the multi-tasking framework while providing reliable
90 interrupt delivery.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_arch_block_interrupts_ao_arch_release_interrupts"></a>2.1.1. ao_arch_block_interrupts/ao_arch_release_interrupts</h3></div></div></div><pre class="literallayout">static inline void
91 ao_arch_block_interrupts(void);
94 ao_arch_release_interrupts(void);</pre><p>These disable/enable interrupt delivery, they may not
95 discard any interrupts. Use these for sections of code that
96 must be atomic with respect to any code run from an
97 interrupt handler.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_arch_save_regs_ao_arch_save_stack_ao_arch_restore_stack"></a>2.1.2. ao_arch_save_regs, ao_arch_save_stack, ao_arch_restore_stack</h3></div></div></div><pre class="literallayout">static inline void
98 ao_arch_save_regs(void);
101 ao_arch_save_stack(void);
104 ao_arch_restore_stack(void);</pre><p>These provide all of the support needed to switch
105 between tasks.. ao_arch_save_regs must save all CPU
106 registers to the current stack, including the
107 interrupt enable state. ao_arch_save_stack records the
108 current stack location in the current ao_task
109 structure. ao_arch_restore_stack switches back to the
110 saved stack, restores all registers and branches to
111 the saved return address.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_arch_wait_interupt"></a>2.1.3. ao_arch_wait_interupt</h3></div></div></div><pre class="literallayout">#define ao_arch_wait_interrupt()</pre><p>This stops the CPU, leaving clocks and interrupts
112 enabled. When an interrupt is received, this must wake up
113 and handle the interrupt. ao_arch_wait_interrupt is entered
114 with interrupts disabled to ensure that there is no gap
115 between determining that no task wants to run and idling the
116 CPU. It must sleep the CPU, process interrupts and then
117 disable interrupts again. If the CPU doesn’t have any
118 reduced power mode, this must at the least allow pending
119 interrupts to be processed.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_gpio_operations"></a>2.2. GPIO operations</h2></div></div></div><p>These functions provide an abstract interface to configure and
120 manipulate GPIO pins.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_gpio_setup"></a>2.2.1. GPIO setup</h3></div></div></div><p>These macros may be invoked at system
121 initialization time to configure pins as
122 needed for system operation. One tricky aspect
123 is that some chips provide direct access to
124 specific GPIO pins while others only provide
125 access to a whole register full of pins. To
126 support this, the GPIO macros provide both
127 port+bit and pin arguments. Simply define the
128 arguments needed for the target platform and
129 leave the others undefined.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_ao_enable_output"></a>ao_enable_output</h4></div></div></div><pre class="literallayout">#define ao_enable_output(port, bit, pin, value)</pre><p>Set the specified port+bit (also called <span class="emphasis"><em>pin</em></span>)
130 for output, initializing to the specified
131 value. The macro must avoid driving the pin
132 with the opposite value if at all possible.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_ao_enable_input"></a>ao_enable_input</h4></div></div></div><pre class="literallayout">#define ao_enable_input(port, bit, mode)</pre><p>Sets the specified port/bit to be an input
133 pin. <span class="emphasis"><em>mode</em></span> is a combination of one or more of
134 the following. Note that some platforms may
135 not support the desired mode. In that case,
136 the value will not be defined so that the
137 program will fail to compile.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
138 AO_EXTI_MODE_PULL_UP. Apply a pull-up to the
139 pin; a disconnected pin will read as 1.
140 </li><li class="listitem">
141 AO_EXTI_MODE_PULL_DOWN. Apply a pull-down to
142 the pin; a disconnected pin will read as 0.
143 </li><li class="listitem">
144 0. Don’t apply either a pull-up or
145 pull-down. A disconnected pin will read an
147 </li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_reading_and_writing_gpio_pins"></a>2.2.2. Reading and writing GPIO pins</h3></div></div></div><p>These macros read and write individual GPIO pins.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_ao_gpio_set"></a>ao_gpio_set</h4></div></div></div><pre class="literallayout">#define ao_gpio_set(port, bit, pin, value)</pre><p>Sets the specified port/bit or pin to
148 the indicated value</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_ao_gpio_get"></a>ao_gpio_get</h4></div></div></div><pre class="literallayout">#define ao_gpio_get(port, bit, pin)</pre><p>Returns either 1 or 0 depending on
149 whether the input to the pin is high
151 == Programming the 8051 with SDCC</p><p>The 8051 is a primitive 8-bit processor, designed in the mists
152 of time in as few transistors as possible. The architecture is
153 highly irregular and includes several separate memory
154 spaces. Furthermore, accessing stack variables is slow, and
155 the stack itself is of limited size. While SDCC papers over
156 the instruction set, it is not completely able to hide the
157 memory architecture from the application designer.</p><p>When built on other architectures, the various SDCC-specific
158 symbols are #defined as empty strings so they don’t affect the
159 compiler.</p></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_8051_memory_spaces"></a>2.3. 8051 memory spaces</h2></div></div></div><p>The <span class="emphasis"><em>data/</em></span>xdata/__code memory spaces below were completely
160 separate in the original 8051 design. In the cc1111, this
161 isn’t true—they all live in a single unified 64kB address
162 space, and so it’s possible to convert any address into a
163 unique 16-bit address. SDCC doesn’t know this, and so a
164 <span class="emphasis"><em>global</em></span> address to SDCC consumes 3 bytes of memory, 1 byte as
165 a tag indicating the memory space and 2 bytes of offset within
166 that space. AltOS avoids these 3-byte addresses as much as
167 possible; using them involves a function call per byte
168 access. The result is that nearly every variable declaration
169 is decorated with a memory space identifier which clutters the
170 code but makes the resulting code far smaller and more
171 efficient.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_data"></a>2.3.1. __data</h3></div></div></div><p>The 8051 can directly address these 128 bytes of
172 memory. This makes them precious so they should be
173 reserved for frequently addressed values. Oh, just to
174 confuse things further, the 8 general registers in the
175 CPU are actually stored in this memory space. There are
176 magic instructions to <span class="emphasis"><em>bank switch</em></span> among 4 banks of
177 these registers located at 0x00 - 0x1F. AltOS uses only
178 the first bank at 0x00 - 0x07, leaving the other 24
179 bytes available for other data.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_idata"></a>2.3.2. __idata</h3></div></div></div><p>There are an additional 128 bytes of internal memory
180 that share the same address space as __data but which
181 cannot be directly addressed. The stack normally
182 occupies this space and so AltOS doesn’t place any
183 static storage here.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_xdata"></a>2.3.3. __xdata</h3></div></div></div><p>This is additional general memory accessed through a
184 single 16-bit address register. The CC1111F32 has 32kB
185 of memory available here. Most program data should live
186 in this memory space.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_pdata"></a>2.3.4. __pdata</h3></div></div></div><p>This is an alias for the first 256 bytes of __xdata
187 memory, but uses a shorter addressing mode with
188 single global 8-bit value for the high 8 bits of the
189 address and any of several 8-bit registers for the low 8
190 bits. AltOS uses a few bits of this memory, it should
191 probably use more.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_code"></a>2.3.5. __code</h3></div></div></div><p>All executable code must live in this address space, but
192 you can stick read-only data here too. It is addressed
193 using the 16-bit address register and special <span class="emphasis"><em>code</em></span>
194 access opcodes. Anything read-only should live in this space.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_bit"></a>2.3.6. __bit</h3></div></div></div><p>The 8051 has 128 bits of bit-addressible memory that
195 lives in the <span class="emphasis"><em>data segment from 0x20 through
196 0x2f. Special instructions access these bits
197 in a single atomic operation. This isn’t so much a
198 separate address space as a special addressing mode for
199 a few bytes in the </em></span>data segment.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_emphasis_sfr_emphasis_sfr16_emphasis_sfr32_emphasis_sbit"></a>2.3.7. <span class="emphasis"><em>sfr, </em></span>sfr16, <span class="emphasis"><em>sfr32, </em></span>sbit</h3></div></div></div><p>Access to physical registers in the device use this mode
200 which declares the variable name, its type and the
201 address it lives at. No memory is allocated for these
202 variables.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_function_calls_on_the_8051"></a>2.4. Function calls on the 8051</h2></div></div></div><p>Because stack addressing is expensive, and stack space
203 limited, the default function call declaration in SDCC
204 allocates all parameters and local variables in static global
205 memory. Just like fortran. This makes these functions
206 non-reentrant, and also consume space for parameters and
207 locals even when they are not running. The benefit is smaller
208 code and faster execution.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_reentrant_functions"></a>2.4.1. __reentrant functions</h3></div></div></div><p>All functions which are re-entrant, either due to recursion
209 or due to a potential context switch while executing, should
210 be marked as __reentrant so that their parameters and local
211 variables get allocated on the stack. This ensures that
212 these values are not overwritten by another invocation of
213 the function.</p><p>Functions which use significant amounts of space for
214 arguments and/or local variables and which are not often
215 invoked can also be marked as __reentrant. The resulting
216 code will be larger, but the savings in memory are
217 frequently worthwhile.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_non___reentrant_functions"></a>2.4.2. Non __reentrant functions</h3></div></div></div><p>All parameters and locals in non-reentrant functions can
218 have data space decoration so that they are allocated in
219 <span class="emphasis"><em>xdata, </em></span>pdata or <span class="emphasis"><em>data space as desired. This can avoid
220 consuming </em></span>data space for infrequently used variables in
221 frequently used functions.</p><p>All library functions called by SDCC, including functions
222 for multiplying and dividing large data types, are
223 non-reentrant. Because of this, interrupt handlers must not
224 invoke any library functions, including the multiply and
225 divide code.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_interrupt_functions"></a>2.4.3. __interrupt functions</h3></div></div></div><p>Interrupt functions are declared with with an __interrupt
226 decoration that includes the interrupt number. SDCC saves
227 and restores all of the registers in these functions and
228 uses the <span class="emphasis"><em>reti</em></span> instruction at the end so that they operate
229 as stand-alone interrupt handlers. Interrupt functions may
230 call the ao_wakeup function to wake AltOS tasks.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_critical_functions_and_statements"></a>2.4.4. __critical functions and statements</h3></div></div></div><p>SDCC has built-in support for suspending interrupts during
231 critical code. Functions marked as <span class="emphasis"><em>critical will have
232 interrupts suspended for the whole period of
233 execution. Individual statements may also be marked as
234 </em></span>critical which blocks interrupts during the execution of
235 that statement. Keeping critical sections as short as
236 possible is key to ensuring that interrupts are handled as
237 quickly as possible. AltOS doesn’t use this form in shared
238 code as other compilers wouldn’t know what to do. Use
239 ao_arch_block_interrupts and ao_arch_release_interrupts instead.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_task_functions"></a>Chapter 3. Task functions</h1></div></div></div><p>This chapter documents how to create, destroy and schedule
240 AltOS tasks.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_add_task"></a>3.1. ao_add_task</h2></div></div></div><pre class="literallayout">void
241 ao_add_task(__xdata struct ao_task * task,
243 __code char *name);</pre><p>This initializes the statically allocated task structure,
244 assigns a name to it (not used for anything but the task
245 display), and the start address. It does not switch to the
246 new task. <span class="emphasis"><em>start</em></span> must not ever return; there is no place
247 to return to.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_exit"></a>3.2. ao_exit</h2></div></div></div><pre class="literallayout">void
248 ao_exit(void)</pre><p>This terminates the current task.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_sleep"></a>3.3. ao_sleep</h2></div></div></div><pre class="literallayout">void
249 ao_sleep(__xdata void *wchan)</pre><p>This suspends the current task until <span class="emphasis"><em>wchan</em></span> is signaled
250 by ao_wakeup, or until the timeout, set by ao_alarm,
251 fires. If <span class="emphasis"><em>wchan</em></span> is signaled, ao_sleep returns 0, otherwise
252 it returns 1. This is the only way to switch to another task.</p><p>Because ao_wakeup wakes every task waiting on a particular
253 location, ao_sleep should be used in a loop that first checks
254 the desired condition, blocks in ao_sleep and then rechecks
255 until the condition is satisfied. If the location may be
256 signaled from an interrupt handler, the code will need to
257 block interrupts around the block of code. Here’s a complete
258 example:</p><pre class="literallayout">ao_arch_block_interrupts();
259 while (!ao_radio_done)
260 ao_sleep(&amp;ao_radio_done);
261 ao_arch_release_interrupts();</pre></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_wakeup"></a>3.4. ao_wakeup</h2></div></div></div><pre class="literallayout">void
262 ao_wakeup(__xdata void *wchan)</pre><p>Wake all tasks blocked on <span class="emphasis"><em>wchan</em></span>. This makes them
263 available to be run again, but does not actually switch
264 to another task. Here’s an example of using this:</p><pre class="literallayout">if (RFIF &amp; RFIF_IM_DONE) {
266 ao_wakeup(&amp;ao_radio_done);
267 RFIF &amp;= ~RFIF_IM_DONE;
268 }</pre><p>Note that this need not block interrupts as the
269 ao_sleep block can only be run from normal mode, and
270 so this sequence can never be interrupted with
271 execution of the other sequence.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_alarm"></a>3.5. ao_alarm</h2></div></div></div><pre class="literallayout">void
272 ao_alarm(uint16_t delay);
275 ao_clear_alarm(void);</pre><p>Schedules an alarm to fire in at least <span class="emphasis"><em>delay</em></span>
276 ticks. If the task is asleep when the alarm fires, it
277 will wakeup and ao_sleep will return 1. ao_clear_alarm
278 resets any pending alarm so that it doesn’t fire at
279 some arbitrary point in the future.</p><pre class="literallayout">ao_alarm(ao_packet_master_delay);
280 ao_arch_block_interrupts();
281 while (!ao_radio_dma_done)
282 if (ao_sleep(&amp;ao_radio_dma_done) != 0)
284 ao_arch_release_interrupts();
285 ao_clear_alarm();</pre><p>In this example, a timeout is set before waiting for
286 incoming radio data. If no data is received before the
287 timeout fires, ao_sleep will return 1 and then this
288 code will abort the radio receive operation.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_start_scheduler"></a>3.6. ao_start_scheduler</h2></div></div></div><pre class="literallayout">void
289 ao_start_scheduler(void);</pre><p>This is called from <span class="emphasis"><em>main</em></span> when the system is all
290 initialized and ready to run. It will not return.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_clock_init"></a>3.7. ao_clock_init</h2></div></div></div><pre class="literallayout">void
291 ao_clock_init(void);</pre><p>This initializes the main CPU clock and switches to it.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_timer_functions"></a>Chapter 4. Timer Functions</h1></div></div></div><p>AltOS sets up one of the CPU timers to run at 100Hz and
292 exposes this tick as the fundemental unit of time. At each
293 interrupt, AltOS increments the counter, and schedules any tasks
294 waiting for that time to pass, then fires off the sensors to
295 collect current data readings. Doing this from the ISR ensures
296 that the values are sampled at a regular rate, independent
297 of any scheduling jitter.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_time"></a>4.1. ao_time</h2></div></div></div><pre class="literallayout">uint16_t
298 ao_time(void)</pre><p>Returns the current system tick count. Note that this is
299 only a 16 bit value, and so it wraps every 655.36 seconds.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_delay"></a>4.2. ao_delay</h2></div></div></div><pre class="literallayout">void
300 ao_delay(uint16_t ticks);</pre><p>Suspend the current task for at least <span class="emphasis"><em>ticks</em></span> clock units.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_timer_set_adc_interval"></a>4.3. ao_timer_set_adc_interval</h2></div></div></div><pre class="literallayout">void
301 ao_timer_set_adc_interval(uint8_t interval);</pre><p>This sets the number of ticks between ADC samples. If set
302 to 0, no ADC samples are generated. AltOS uses this to
303 slow down the ADC sampling rate to save power.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_timer_init"></a>4.4. ao_timer_init</h2></div></div></div><pre class="literallayout">void
304 ao_timer_init(void)</pre><p>This turns on the 100Hz tick. It is required for any of the
305 time-based functions to work. It should be called by <span class="emphasis"><em>main</em></span>
306 before ao_start_scheduler.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_altos_mutexes"></a>Chapter 5. AltOS Mutexes</h1></div></div></div><p>AltOS provides mutexes as a basic synchronization primitive. Each
307 mutexes is simply a byte of memory which holds 0 when the mutex
308 is free or the task id of the owning task when the mutex is
309 owned. Mutex calls are checked—attempting to acquire a mutex
310 already held by the current task or releasing a mutex not held
311 by the current task will both cause a panic.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_mutex_get"></a>5.1. ao_mutex_get</h2></div></div></div><pre class="literallayout">void
312 ao_mutex_get(__xdata uint8_t *mutex);</pre><p>Acquires the specified mutex, blocking if the mutex is
313 owned by another task.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_mutex_put"></a>5.2. ao_mutex_put</h2></div></div></div><pre class="literallayout">void
314 ao_mutex_put(__xdata uint8_t *mutex);</pre><p>Releases the specified mutex, waking up all tasks waiting
315 for it.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_dma_engine"></a>Chapter 6. DMA engine</h1></div></div></div><p>The CC1111 and STM32L both contain a useful bit of extra
316 hardware in the form of a number of programmable DMA
317 engines. They can be configured to copy data in memory, or
318 between memory and devices (or even between two devices). AltOS
319 exposes a general interface to this hardware and uses it to
320 handle both internal and external devices.</p><p>Because the CC1111 and STM32L DMA engines are different, the
321 interface to them is also different. As the DMA engines are
322 currently used to implement platform-specific drivers, this
323 isn’t yet a problem.</p><p>Code using a DMA engine should allocate one at startup
324 time. There is no provision to free them, and if you run out,
325 AltOS will simply panic.</p><p>During operation, the DMA engine is initialized with the
326 transfer parameters. Then it is started, at which point it
327 awaits a suitable event to start copying data. When copying data
328 from hardware to memory, that trigger event is supplied by the
329 hardware device. When copying data from memory to hardware, the
330 transfer is usually initiated by software.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_cc1111_dma_engine"></a>6.1. CC1111 DMA Engine</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_alloc"></a>6.1.1. ao_dma_alloc</h3></div></div></div><pre class="literallayout">uint8_t
331 ao_dma_alloc(__xdata uint8_t *done)</pre><p>Allocate a DMA engine, returning the
332 identifier. <span class="emphasis"><em>done</em></span> is cleared when the DMA is
333 started, and then receives the AO_DMA_DONE bit
334 on a successful transfer or the AO_DMA_ABORTED
335 bit if ao_dma_abort was called. Note that it
336 is possible to get both bits if the transfer
337 was aborted after it had finished.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_set_transfer"></a>6.1.2. ao_dma_set_transfer</h3></div></div></div><pre class="literallayout">void
338 ao_dma_set_transfer(uint8_t id,
339 void __xdata *srcaddr,
340 void __xdata *dstaddr,
343 uint8_t cfg1)</pre><p>Initializes the specified dma engine to copy
344 data from <span class="emphasis"><em>srcaddr</em></span> to <span class="emphasis"><em>dstaddr</em></span> for <span class="emphasis"><em>count</em></span>
345 units. cfg0 and cfg1 are values directly out
346 of the CC1111 documentation and tell the DMA
347 engine what the transfer unit size, direction
348 and step are.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_start"></a>6.1.3. ao_dma_start</h3></div></div></div><pre class="literallayout">void
349 ao_dma_start(uint8_t id);</pre><p>Arm the specified DMA engine and await a
350 signal from either hardware or software to
351 start transferring data.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_trigger"></a>6.1.4. ao_dma_trigger</h3></div></div></div><pre class="literallayout">void
352 ao_dma_trigger(uint8_t id)</pre><p>Trigger the specified DMA engine to start
353 copying data.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_abort"></a>6.1.5. ao_dma_abort</h3></div></div></div><pre class="literallayout">void
354 ao_dma_abort(uint8_t id)</pre><p>Terminate any in-progress DMA transaction,
355 marking its <span class="emphasis"><em>done</em></span> variable with the
356 AO_DMA_ABORTED bit.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_stm32l_dma_engine"></a>6.2. STM32L DMA Engine</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_alloc_2"></a>6.2.1. ao_dma_alloc</h3></div></div></div><pre class="literallayout">uint8_t ao_dma_done[];
359 ao_dma_alloc(uint8_t index);</pre><p>Reserve a DMA engine for exclusive use by one
360 driver.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_set_transfer_2"></a>6.2.2. ao_dma_set_transfer</h3></div></div></div><pre class="literallayout">void
361 ao_dma_set_transfer(uint8_t id,
365 uint32_t ccr);</pre><p>Initializes the specified dma engine to copy
366 data between <span class="emphasis"><em>peripheral</em></span> and <span class="emphasis"><em>memory</em></span> for
367 <span class="emphasis"><em>count</em></span> units. <span class="emphasis"><em>ccr</em></span> is a value directly out
368 of the STM32L documentation and tells the DMA
369 engine what the transfer unit size, direction
370 and step are.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_set_isr"></a>6.2.3. ao_dma_set_isr</h3></div></div></div><pre class="literallayout">void
371 ao_dma_set_isr(uint8_t index, void (*isr)(int))</pre><p>This sets a function to be called when the DMA
372 transfer completes in lieu of setting the
373 ao_dma_done bits. Use this when some work
374 needs to be done when the DMA finishes that
375 cannot wait until user space resumes.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_start_2"></a>6.2.4. ao_dma_start</h3></div></div></div><pre class="literallayout">void
376 ao_dma_start(uint8_t id);</pre><p>Arm the specified DMA engine and await a
377 signal from either hardware or software to
378 start transferring data. <span class="emphasis"><em>ao_dma_done[index]</em></span>
379 is cleared when the DMA is started, and then
380 receives the AO_DMA_DONE bit on a successful
381 transfer or the AO_DMA_ABORTED bit if
382 ao_dma_abort was called. Note that it is
383 possible to get both bits if the transfer was
384 aborted after it had finished.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_done_transfer"></a>6.2.5. ao_dma_done_transfer</h3></div></div></div><pre class="literallayout">void
385 ao_dma_done_transfer(uint8_t id);</pre><p>Signals that a specific DMA engine is done
386 being used. This allows multiple drivers to
387 use the same DMA engine safely.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_dma_abort_2"></a>6.2.6. ao_dma_abort</h3></div></div></div><pre class="literallayout">void
388 ao_dma_abort(uint8_t id)</pre><p>Terminate any in-progress DMA transaction,
389 marking its <span class="emphasis"><em>done</em></span> variable with the
390 AO_DMA_ABORTED bit.</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_stdio_interface"></a>Chapter 7. Stdio interface</h1></div></div></div><p>AltOS offers a stdio interface over USB, serial and the RF
391 packet link. This provides for control of the device locally or
392 remotely. This is hooked up to the stdio functions by providing
393 the standard putchar/getchar/flush functions. These
394 automatically multiplex the available communication channels;
395 output is always delivered to the channel which provided the
396 most recent input.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_putchar"></a>7.1. putchar</h2></div></div></div><pre class="literallayout">void
397 putchar(char c)</pre><p>Delivers a single character to the current console
398 device.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_getchar"></a>7.2. getchar</h2></div></div></div><pre class="literallayout">char
399 getchar(void)</pre><p>Reads a single character from any of the available
400 console devices. The current console device is set to
401 that which delivered this character. This blocks until
402 a character is available.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_flush"></a>7.3. flush</h2></div></div></div><pre class="literallayout">void
403 flush(void)</pre><p>Flushes the current console device output buffer. Any
404 pending characters will be delivered to the target device.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_add_stdio"></a>7.4. ao_add_stdio</h2></div></div></div><pre class="literallayout">void
405 ao_add_stdio(char (*pollchar)(void),
406 void (*putchar)(char),
407 void (*flush)(void))</pre><p>This adds another console device to the available
408 list.</p><p><span class="emphasis"><em>pollchar</em></span> returns either an available character or
409 AO_READ_AGAIN if none is available. Significantly, it does
410 not block. The device driver must set <span class="emphasis"><em>ao_stdin_ready</em></span> to
411 1 and call ao_wakeup(&ao_stdin_ready) when it receives
412 input to tell getchar that more data is available, at
413 which point <span class="emphasis"><em>pollchar</em></span> will be called again.</p><p><span class="emphasis"><em>putchar</em></span> queues a character for output, flushing if the output buffer is
414 full. It may block in this case.</p><p><span class="emphasis"><em>flush</em></span> forces the output buffer to be flushed. It may
415 block until the buffer is delivered, but it is not
416 required to do so.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_command_line_interface"></a>Chapter 8. Command line interface</h1></div></div></div><p>AltOS includes a simple command line parser which is hooked up
417 to the stdio interfaces permitting remote control of the
418 device over USB, serial or the RF link as desired. Each
419 command uses a single character to invoke it, the remaining
420 characters on the line are available as parameters to the
421 command.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_cmd_register"></a>8.1. ao_cmd_register</h2></div></div></div><pre class="literallayout">void
422 ao_cmd_register(__code struct ao_cmds *cmds)</pre><p>This registers a set of commands with the command
423 parser. There is a fixed limit on the number of command
424 sets, the system will panic if too many are registered.
425 Each command is defined by a struct ao_cmds entry:</p><pre class="literallayout">struct ao_cmds {
429 };</pre><p><span class="emphasis"><em>cmd</em></span> is the character naming the command. <span class="emphasis"><em>func</em></span> is the
430 function to invoke and <span class="emphasis"><em>help</em></span> is a string displayed by the
431 <span class="emphasis"><em>?</em></span> command. Syntax errors found while executing <span class="emphasis"><em>func</em></span>
432 should be indicated by modifying the global ao_cmd_status
433 variable with one of the following values:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
436 The command was parsed successfully. There is no need
437 to assign this value, it is the default.
438 </dd><dt><span class="term">
441 A token in the line was invalid, such as a number
442 containing invalid characters. The low-level lexing
443 functions already assign this value as needed.
444 </dd><dt><span class="term">
447 The command line is invalid for some reason other than
449 </dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_cmd_lex"></a>8.2. ao_cmd_lex</h2></div></div></div><pre class="literallayout">void
450 ao_cmd_lex(void);</pre><p>This gets the next character out of the command line
451 buffer and sticks it into ao_cmd_lex_c. At the end of
452 the line, ao_cmd_lex_c will get a newline (<span class="emphasis"><em>\n</em></span>)
453 character.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_cmd_put16"></a>8.3. ao_cmd_put16</h2></div></div></div><pre class="literallayout">void
454 ao_cmd_put16(uint16_t v);</pre><p>Writes <span class="emphasis"><em>v</em></span> as four hexadecimal characters.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_cmd_put8"></a>8.4. ao_cmd_put8</h2></div></div></div><pre class="literallayout">void
455 ao_cmd_put8(uint8_t v);</pre><p>Writes <span class="emphasis"><em>v</em></span> as two hexadecimal characters.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_cmd_white"></a>8.5. ao_cmd_white</h2></div></div></div><pre class="literallayout">void
456 ao_cmd_white(void)</pre><p>This skips whitespace by calling ao_cmd_lex while
457 ao_cmd_lex_c is either a space or tab. It does not
458 skip any characters if ao_cmd_lex_c already non-white.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_cmd_hex"></a>8.6. ao_cmd_hex</h2></div></div></div><pre class="literallayout">void
459 ao_cmd_hex(void)</pre><p>This reads a 16-bit hexadecimal value from the command
460 line with optional leading whitespace. The resulting
461 value is stored in ao_cmd_lex_i;</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_cmd_decimal"></a>8.7. ao_cmd_decimal</h2></div></div></div><pre class="literallayout">void
462 ao_cmd_decimal(void)</pre><p>This reads a 32-bit decimal value from the command
463 line with optional leading whitespace. The resulting
464 value is stored in ao_cmd_lex_u32 and the low 16 bits
465 are stored in ao_cmd_lex_i;</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_match_word"></a>8.8. ao_match_word</h2></div></div></div><pre class="literallayout">uint8_t
466 ao_match_word(__code char *word)</pre><p>This checks to make sure that <span class="emphasis"><em>word</em></span> occurs on the
467 command line. It does not skip leading white space. If
468 <span class="emphasis"><em>word</em></span> is found, then 1 is returned. Otherwise,
469 ao_cmd_status is set to ao_cmd_syntax_error and 0 is
470 returned.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_cmd_init"></a>8.9. ao_cmd_init</h2></div></div></div><pre class="literallayout">void
471 ao_cmd_init(void</pre><p>Initializes the command system, setting up the
472 built-in commands and adding a task to run the command
473 processing loop. It should be called by <span class="emphasis"><em>main</em></span> before
474 ao_start_scheduler.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_usb_target_device"></a>Chapter 9. USB target device</h1></div></div></div><p>AltOS contains a full-speed USB target device driver. It can
475 be programmed to offer any kind of USB target, but to simplify
476 interactions with a variety of operating systems, AltOS
477 provides only a single target device profile, that of a USB
478 modem which has native drivers for Linux, Windows and Mac OS
479 X. It would be easy to change the code to provide an alternate
480 target device if necessary.</p><p>To the rest of the system, the USB device looks like a simple
481 two-way byte stream. It can be hooked into the command line
482 interface if desired, offering control of the device over the
483 USB link. Alternatively, the functions can be accessed
484 directly to provide for USB-specific I/O.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_usb_flush"></a>9.1. ao_usb_flush</h2></div></div></div><pre class="literallayout">void
485 ao_usb_flush(void);</pre><p>Flushes any pending USB output. This queues an <span class="emphasis"><em>IN</em></span>
486 packet to be delivered to the USB host if there is
487 pending data, or if the last IN packet was full to
488 indicate to the host that there isn’t any more pending
489 data available.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_usb_putchar"></a>9.2. ao_usb_putchar</h2></div></div></div><pre class="literallayout">void
490 ao_usb_putchar(char c);</pre><p>If there is a pending <span class="emphasis"><em>IN</em></span> packet awaiting delivery to
491 the host, this blocks until that has been
492 fetched. Then, this adds a byte to the pending IN
493 packet for delivery to the USB host. If the USB packet
494 is full, this queues the <span class="emphasis"><em>IN</em></span> packet for delivery.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_usb_pollchar"></a>9.3. ao_usb_pollchar</h2></div></div></div><pre class="literallayout">char
495 ao_usb_pollchar(void);</pre><p>If there are no characters remaining in the last <span class="emphasis"><em>OUT</em></span>
496 packet received, this returns
497 AO_READ_AGAIN. Otherwise, it returns the next
498 character, reporting to the host that it is ready for
499 more data when the last character is gone.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_usb_getchar"></a>9.4. ao_usb_getchar</h2></div></div></div><pre class="literallayout">char
500 ao_usb_getchar(void);</pre><p>This uses ao_pollchar to receive the next character,
501 blocking while ao_pollchar returns AO_READ_AGAIN.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_usb_disable"></a>9.5. ao_usb_disable</h2></div></div></div><pre class="literallayout">void
502 ao_usb_disable(void);</pre><p>This turns off the USB controller. It will no longer
503 respond to host requests, nor return
504 characters. Calling any of the i/o routines while the
505 USB device is disabled is undefined, and likely to
506 break things. Disabling the USB device when not needed
507 saves power.</p><p>Note that neither TeleDongle v0.2 nor TeleMetrum v1
508 are able to signal to the USB host that they have
509 disconnected, so after disabling the USB device, it’s
510 likely that the cable will need to be disconnected and
511 reconnected before it will work again.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_usb_enable"></a>9.6. ao_usb_enable</h2></div></div></div><pre class="literallayout">void
512 ao_usb_enable(void);</pre><p>This turns the USB controller on again after it has
513 been disabled. See the note above about needing to
514 physically remove and re-insert the cable to get the
515 host to re-initialize the USB link.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_usb_init"></a>9.7. ao_usb_init</h2></div></div></div><pre class="literallayout">void
516 ao_usb_init(void);</pre><p>This turns the USB controller on, adds a task to
517 handle the control end point and adds the usb I/O
518 functions to the stdio system. Call this from main
519 before ao_start_scheduler.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_serial_peripherals"></a>Chapter 10. Serial peripherals</h1></div></div></div><p>The CC1111 provides two USART peripherals. AltOS uses one for
520 asynch serial data, generally to communicate with a GPS
521 device, and the other for a SPI bus. The UART is configured to
522 operate in 8-bits, no parity, 1 stop bit framing. The default
523 configuration has clock settings for 4800, 9600 and 57600 baud
524 operation. Additional speeds can be added by computing
525 appropriate clock values.</p><p>To prevent loss of data, AltOS provides receive and transmit
526 fifos of 32 characters each.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_serial_getchar"></a>10.1. ao_serial_getchar</h2></div></div></div><pre class="literallayout">char
527 ao_serial_getchar(void);</pre><p>Returns the next character from the receive fifo, blocking
528 until a character is received if the fifo is empty.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_serial_putchar"></a>10.2. ao_serial_putchar</h2></div></div></div><pre class="literallayout">void
529 ao_serial_putchar(char c);</pre><p>Adds a character to the transmit fifo, blocking if the
530 fifo is full. Starts transmitting characters.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_serial_drain"></a>10.3. ao_serial_drain</h2></div></div></div><pre class="literallayout">void
531 ao_serial_drain(void);</pre><p>Blocks until the transmit fifo is empty. Used internally
532 when changing serial speeds.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_serial_set_speed"></a>10.4. ao_serial_set_speed</h2></div></div></div><pre class="literallayout">void
533 ao_serial_set_speed(uint8_t speed);</pre><p>Changes the serial baud rate to one of
534 AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or
535 AO_SERIAL_SPEED_57600. This first flushes the transmit
536 fifo using ao_serial_drain.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_serial_init"></a>10.5. ao_serial_init</h2></div></div></div><pre class="literallayout">void
537 ao_serial_init(void)</pre><p>Initializes the serial peripheral. Call this from <span class="emphasis"><em>main</em></span>
538 before jumping to ao_start_scheduler. The default speed
539 setting is AO_SERIAL_SPEED_4800.</p></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="_cc1111_cc1120_cc1200_radio_peripheral"></a>Chapter 11. CC1111/CC1120/CC1200 Radio peripheral</h1></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_radio_introduction"></a>11.1. Radio Introduction</h2></div></div></div><p>The CC1111, CC1120 and CC1200 radio transceiver sends
540 and receives digital packets with forward error
541 correction and detection. The AltOS driver is fairly
542 specific to the needs of the TeleMetrum and TeleDongle
543 devices, using it for other tasks may require
544 customization of the driver itself. There are three
545 basic modes of operation:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
546 Telemetry mode. In this mode, TeleMetrum transmits telemetry
547 frames at a fixed rate. The frames are of fixed size. This
548 is strictly a one-way communication from TeleMetrum to
550 </li><li class="listitem">
551 Packet mode. In this mode, the radio is used to create a
552 reliable duplex byte stream between TeleDongle and
553 TeleMetrum. This is an asymmetrical protocol with
554 TeleMetrum only transmitting in response to a packet sent
555 from TeleDongle. Thus getting data from TeleMetrum to
556 TeleDongle requires polling. The polling rate is adaptive,
557 when no data has been received for a while, the rate slows
558 down. The packets are checked at both ends and invalid data
560 </li></ol></div><p>On the TeleMetrum side, the packet link is hooked into the
561 stdio mechanism, providing an alternate data path for the
562 command processor. It is enabled when the unit boots up in
563 <span class="emphasis"><em>idle</em></span> mode.</p><p>On the TeleDongle side, the packet link is enabled with a
564 command; data from the stdio package is forwarded over the
565 packet link providing a connection from the USB command
566 stream to the remote TeleMetrum device.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
567 Radio Direction Finding mode. In this mode, TeleMetrum
568 constructs a special packet that sounds like an audio tone
569 when received by a conventional narrow-band FM
570 receiver. This is designed to provide a beacon to track the
571 device when other location mechanisms fail.
572 </li></ol></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_radio_set_telemetry"></a>11.2. ao_radio_set_telemetry</h2></div></div></div><pre class="literallayout">void
573 ao_radio_set_telemetry(void);</pre><p>Configures the radio to send or receive telemetry
574 packets. This includes packet length, modulation scheme and
575 other RF parameters. It does not include the base frequency
576 or channel though. Those are set at the time of transmission
577 or reception, in case the values are changed by the user.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_radio_set_packet"></a>11.3. ao_radio_set_packet</h2></div></div></div><pre class="literallayout">void
578 ao_radio_set_packet(void);</pre><p>Configures the radio to send or receive packet data. This
579 includes packet length, modulation scheme and other RF
580 parameters. It does not include the base frequency or
581 channel though. Those are set at the time of transmission or
582 reception, in case the values are changed by the user.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_radio_set_rdf"></a>11.4. ao_radio_set_rdf</h2></div></div></div><pre class="literallayout">void
583 ao_radio_set_rdf(void);</pre><p>Configures the radio to send RDF <span class="emphasis"><em>packets</em></span>. An RDF <span class="emphasis"><em>packet</em></span>
584 is a sequence of hex 0x55 bytes sent at a base bit rate of
585 2kbps using a 5kHz deviation. All of the error correction
586 and data whitening logic is turned off so that the resulting
587 modulation is received as a 1kHz tone by a conventional 70cm
588 FM audio receiver.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_radio_idle"></a>11.5. ao_radio_idle</h2></div></div></div><pre class="literallayout">void
589 ao_radio_idle(void);</pre><p>Sets the radio device to idle mode, waiting until it reaches
590 that state. This will terminate any in-progress transmit or
591 receive operation.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_radio_get"></a>11.6. ao_radio_get</h2></div></div></div><pre class="literallayout">void
592 ao_radio_get(void);</pre><p>Acquires the radio mutex and then configures the radio
593 frequency using the global radio calibration and channel
594 values.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_radio_put"></a>11.7. ao_radio_put</h2></div></div></div><pre class="literallayout">void
595 ao_radio_put(void);</pre><p>Releases the radio mutex.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_ao_radio_abort"></a>11.8. ao_radio_abort</h2></div></div></div><pre class="literallayout">void
596 ao_radio_abort(void);</pre><p>Aborts any transmission or reception process by aborting the
597 associated DMA object and calling ao_radio_idle to terminate
598 the radio operation.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_radio_telemetry"></a>11.9. Radio Telemetry</h2></div></div></div><p>In telemetry mode, you can send or receive a telemetry
599 packet. The data from receiving a packet also includes the RSSI
600 and status values supplied by the receiver. These are added
601 after the telemetry data.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_radio_send"></a>11.9.1. ao_radio_send</h3></div></div></div><pre class="literallayout">void
602 ao_radio_send(__xdata struct ao_telemetry *telemetry);</pre><p>This sends the specific telemetry packet, waiting for the
603 transmission to complete. The radio must have been set to
604 telemetry mode. This function calls ao_radio_get() before
605 sending, and ao_radio_put() afterwards, to correctly
606 serialize access to the radio device.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_radio_recv"></a>11.9.2. ao_radio_recv</h3></div></div></div><pre class="literallayout">void
607 ao_radio_recv(__xdata struct ao_radio_recv *radio);</pre><p>This blocks waiting for a telemetry packet to be received.
608 The radio must have been set to telemetry mode. This
609 function calls ao_radio_get() before receiving, and
610 ao_radio_put() afterwards, to correctly serialize access
611 to the radio device. This returns non-zero if a packet was
612 received, or zero if the operation was aborted (from some
613 other task calling ao_radio_abort()).</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_radio_direction_finding"></a>11.10. Radio Direction Finding</h2></div></div></div><p>In radio direction finding mode, there’s just one function to
614 use</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_radio_rdf"></a>11.10.1. ao_radio_rdf</h3></div></div></div><pre class="literallayout">void
615 ao_radio_rdf(int ms);</pre><p>This sends an RDF packet lasting for the specified amount
616 of time. The maximum length is 1020 ms.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="_radio_packet_mode"></a>11.11. Radio Packet Mode</h2></div></div></div><p>Packet mode is asymmetrical and is configured at compile time
617 for either master or slave mode (but not both). The basic I/O
618 functions look the same at both ends, but the internals are
619 different, along with the initialization steps.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_packet_putchar"></a>11.11.1. ao_packet_putchar</h3></div></div></div><pre class="literallayout">void
620 ao_packet_putchar(char c);</pre><p>If the output queue is full, this first blocks waiting for
621 that data to be delivered. Then, queues a character for
622 packet transmission. On the master side, this will
623 transmit a packet if the output buffer is full. On the
624 slave side, any pending data will be sent the next time
625 the master polls for data.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_packet_pollchar"></a>11.11.2. ao_packet_pollchar</h3></div></div></div><pre class="literallayout">char
626 ao_packet_pollchar(void);</pre><p>This returns a pending input character if available,
627 otherwise returns AO_READ_AGAIN. On the master side, if
628 this empties the buffer, it triggers a poll for more data.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_packet_slave_start"></a>11.11.3. ao_packet_slave_start</h3></div></div></div><pre class="literallayout">void
629 ao_packet_slave_start(void);</pre><p>This is available only on the slave side and starts a task
630 to listen for packet data.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_packet_slave_stop"></a>11.11.4. ao_packet_slave_stop</h3></div></div></div><pre class="literallayout">void
631 ao_packet_slave_stop(void);</pre><p>Disables the packet slave task, stopping the radio receiver.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_packet_slave_init"></a>11.11.5. ao_packet_slave_init</h3></div></div></div><pre class="literallayout">void
632 ao_packet_slave_init(void);</pre><p>Adds the packet stdio functions to the stdio package so
633 that when packet slave mode is enabled, characters will
634 get send and received through the stdio functions.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="_ao_packet_master_init"></a>11.11.6. ao_packet_master_init</h3></div></div></div><pre class="literallayout">void
635 ao_packet_master_init(void);</pre><p>Adds the <span class="emphasis"><em>p</em></span> packet forward command to start packet mode.</p></div></div></div></div></body></html>
projects / web / altusmetrum / blob