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

   1 <!DOCTYPE html>
   2 <html lang="en">
   3 <head>
   4 <meta charset="UTF-8">
   5 <meta http-equiv="X-UA-Compatible" content="IE=edge">
   6 <meta name="viewport" content="width=device-width, initial-scale=1.0">
   7 <meta name="generator" content="Asciidoctor 2.0.10">
   8 <meta name="author" content="Keith Packard">
   9 <title>AltOS</title>
  10 <link rel="stylesheet" href="./am.css">
  11 </head>
  12 <body class="book">
  13 <div id="header">
  14 <h1>AltOS</h1>
  15 <div class="details">
  16 <span id="author" class="author">Keith Packard</span><br>
  17 <span id="email" class="email"><a href="mailto:keithp@keithp.com">keithp@keithp.com</a></span><br>
  18 <span id="revdate">29 Sep 2020</span>
  19 </div>
  20 <div id="toc" class="toc">
  21 <div id="toctitle">Table of Contents</div>
  22 <ul class="sectlevel1">
  23 <li><a href="#_license">License</a></li>
  24 <li><a href="#_overview">1. Overview</a></li>
  25 <li><a href="#_altos_porting_layer">2. AltOS Porting Layer</a>
  26 <ul class="sectlevel2">
  27 <li><a href="#_low_level_cpu_operations">2.1. Low-level CPU operations</a></li>
  28 <li><a href="#_gpio_operations">2.2. GPIO operations</a></li>
  29 <li><a href="#_8051_memory_spaces">2.3. 8051 memory spaces</a></li>
  30 <li><a href="#_function_calls_on_the_8051">2.4. Function calls on the 8051</a></li>
  31 </ul>
  32 </li>
  33 <li><a href="#_task_functions">3. Task functions</a>
  34 <ul class="sectlevel2">
  35 <li><a href="#_ao_add_task">3.1. ao_add_task</a></li>
  36 <li><a href="#_ao_exit">3.2. ao_exit</a></li>
  37 <li><a href="#_ao_sleep">3.3. ao_sleep</a></li>
  38 <li><a href="#_ao_wakeup">3.4. ao_wakeup</a></li>
  39 <li><a href="#_ao_alarm">3.5. ao_alarm</a></li>
  40 <li><a href="#_ao_start_scheduler">3.6. ao_start_scheduler</a></li>
  41 <li><a href="#_ao_clock_init">3.7. ao_clock_init</a></li>
  42 </ul>
  43 </li>
  44 <li><a href="#_timer_functions">4. Timer Functions</a>
  45 <ul class="sectlevel2">
  46 <li><a href="#_ao_time">4.1. ao_time</a></li>
  47 <li><a href="#_ao_delay">4.2. ao_delay</a></li>
  48 <li><a href="#_ao_timer_set_adc_interval">4.3. ao_timer_set_adc_interval</a></li>
  49 <li><a href="#_ao_timer_init">4.4. ao_timer_init</a></li>
  50 </ul>
  51 </li>
  52 <li><a href="#_altos_mutexes">5. AltOS Mutexes</a>
  53 <ul class="sectlevel2">
  54 <li><a href="#_ao_mutex_get">5.1. ao_mutex_get</a></li>
  55 <li><a href="#_ao_mutex_put">5.2. ao_mutex_put</a></li>
  56 </ul>
  57 </li>
  58 <li><a href="#_dma_engine">6. DMA engine</a>
  59 <ul class="sectlevel2">
  60 <li><a href="#_cc1111_dma_engine">6.1. CC1111 DMA Engine</a></li>
  61 <li><a href="#_stm32l_dma_engine">6.2. STM32L DMA Engine</a></li>
  62 </ul>
  63 </li>
  64 <li><a href="#_stdio_interface">7. Stdio interface</a>
  65 <ul class="sectlevel2">
  66 <li><a href="#_putchar">7.1. putchar</a></li>
  67 <li><a href="#_getchar">7.2. getchar</a></li>
  68 <li><a href="#_flush">7.3. flush</a></li>
  69 <li><a href="#_ao_add_stdio">7.4. ao_add_stdio</a></li>
  70 </ul>
  71 </li>
  72 <li><a href="#_command_line_interface">8. Command line interface</a>
  73 <ul class="sectlevel2">
  74 <li><a href="#_ao_cmd_register">8.1. ao_cmd_register</a></li>
  75 <li><a href="#_ao_cmd_lex">8.2. ao_cmd_lex</a></li>
  76 <li><a href="#_ao_cmd_put16">8.3. ao_cmd_put16</a></li>
  77 <li><a href="#_ao_cmd_put8">8.4. ao_cmd_put8</a></li>
  78 <li><a href="#_ao_cmd_white">8.5. ao_cmd_white</a></li>
  79 <li><a href="#_ao_cmd_hex">8.6. ao_cmd_hex</a></li>
  80 <li><a href="#_ao_cmd_decimal">8.7. ao_cmd_decimal</a></li>
  81 <li><a href="#_ao_match_word">8.8. ao_match_word</a></li>
  82 <li><a href="#_ao_cmd_init">8.9. ao_cmd_init</a></li>
  83 </ul>
  84 </li>
  85 <li><a href="#_usb_target_device">9. USB target device</a>
  86 <ul class="sectlevel2">
  87 <li><a href="#_ao_usb_flush">9.1. ao_usb_flush</a></li>
  88 <li><a href="#_ao_usb_putchar">9.2. ao_usb_putchar</a></li>
  89 <li><a href="#_ao_usb_pollchar">9.3. ao_usb_pollchar</a></li>
  90 <li><a href="#_ao_usb_getchar">9.4. ao_usb_getchar</a></li>
  91 <li><a href="#_ao_usb_disable">9.5. ao_usb_disable</a></li>
  92 <li><a href="#_ao_usb_enable">9.6. ao_usb_enable</a></li>
  93 <li><a href="#_ao_usb_init">9.7. ao_usb_init</a></li>
  94 </ul>
  95 </li>
  96 <li><a href="#_serial_peripherals">10. Serial peripherals</a>
  97 <ul class="sectlevel2">
  98 <li><a href="#_ao_serial_getchar">10.1. ao_serial_getchar</a></li>
  99 <li><a href="#_ao_serial_putchar">10.2. ao_serial_putchar</a></li>
 100 <li><a href="#_ao_serial_drain">10.3. ao_serial_drain</a></li>
 101 <li><a href="#_ao_serial_set_speed">10.4. ao_serial_set_speed</a></li>
 102 <li><a href="#_ao_serial_init">10.5. ao_serial_init</a></li>
 103 </ul>
 104 </li>
 105 <li><a href="#_cc1111cc1120cc1200_radio_peripheral">11. CC1111/CC1120/CC1200 Radio peripheral</a>
 106 <ul class="sectlevel2">
 107 <li><a href="#_radio_introduction">11.1. Radio Introduction</a></li>
 108 <li><a href="#_ao_radio_set_telemetry">11.2. ao_radio_set_telemetry</a></li>
 109 <li><a href="#_ao_radio_set_packet">11.3. ao_radio_set_packet</a></li>
 110 <li><a href="#_ao_radio_set_rdf">11.4. ao_radio_set_rdf</a></li>
 111 <li><a href="#_ao_radio_idle">11.5. ao_radio_idle</a></li>
 112 <li><a href="#_ao_radio_get">11.6. ao_radio_get</a></li>
 113 <li><a href="#_ao_radio_put">11.7. ao_radio_put</a></li>
 114 <li><a href="#_ao_radio_abort">11.8. ao_radio_abort</a></li>
 115 <li><a href="#_radio_telemetry">11.9. Radio Telemetry</a></li>
 116 <li><a href="#_radio_direction_finding">11.10. Radio Direction Finding</a></li>
 117 <li><a href="#_radio_packet_mode">11.11. Radio Packet Mode</a></li>
 118 </ul>
 119 </li>
 120 </ul>
 121 </div>
 122 </div>
 123 <div id="content">
 124 <div id="preamble">
 125 <div class="sectionbody">
 126 <div id="logo" class="imageblock">
 127 <div class="content">
 128 <a class="image" href="https://altusmetrum.org"><img src="altusmetrum-oneline.svg" alt="Altus Metrum"></a>
 129 </div>
 130 </div>
 131 </div>
 132 </div>
 133 <div class="sect1">
 134 <h2 id="_license">License</h2>
 135 <div class="sectionbody">
 136 <div class="paragraph">
 137 <p>Copyright © 2018 Bdale Garbee and Keith Packard</p>
 138 </div>
 139 <div class="paragraph">
 140 <p>This document is released under the terms of the <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons ShareAlike 3.0 License</a></p>
 141 </div>
 142 </div>
 143 </div>
 144 <div class="sect1">
 145 <h2 id="_overview">1. Overview</h2>
 146 <div class="sectionbody">
 147 <div class="paragraph">
 148 <p>AltOS is a operating system built for a variety of
 149 microcontrollers used in Altus Metrum devices. It has a simple
 150 porting layer for each CPU while providing a convenient
 151 operating enviroment for the developer. AltOS currently
 152 supports three different CPUs:</p>
 153 </div>
 154 <div class="ulist">
 155 <ul>
 156 <li>
 157 <p>STM32L series from ST Microelectronics. This ARM Cortex-M3
 158 based microcontroller offers low power consumption and a
 159 wide variety of built-in peripherals. Altus Metrum uses this
 160 in the TeleMega, MegaDongle and TeleLCO projects.</p>
 161 </li>
 162 <li>
 163 <p>CC1111 from Texas Instruments. This device includes a
 164 fabulous 10mW digital RF transceiver along with an
 165 8051-compatible processor core and a range of
 166 peripherals. This is used in the TeleMetrum, TeleMini,
 167 TeleDongle and TeleFire projects which share the need for a
 168 small microcontroller and an RF interface.</p>
 169 </li>
 170 <li>
 171 <p>ATmega32U4 from Atmel. This 8-bit AVR microcontroller is one
 172 of the many used to create Arduino boards. The 32U4 includes
 173 a USB interface, making it easy to connect to other
 174 computers. Altus Metrum used this in prototypes of the
 175 TeleScience and TelePyro boards; those have been switched to
 176 the STM32L which is more capable and cheaper.</p>
 177 </li>
 178 </ul>
 179 </div>
 180 <div class="paragraph">
 181 <p>Among the features of AltOS are:</p>
 182 </div>
 183 <div class="ulist">
 184 <ul>
 185 <li>
 186 <p>Multi-tasking. While microcontrollers often don&#8217;t
 187 provide separate address spaces, it&#8217;s often easier to write
 188 code that operates in separate threads instead of tying
 189 everything into one giant event loop.</p>
 190 </li>
 191 <li>
 192 <p>Non-preemptive. This increases latency for thread
 193 switching but reduces the number of places where context
 194 switching can occur. It also simplifies the operating system
 195 design somewhat. Nothing in the target system (rocket flight
 196 control) has tight timing requirements, and so this seems like
 197 a reasonable compromise.</p>
 198 </li>
 199 <li>
 200 <p>Sleep/wakeup scheduling. Taken directly from ancient
 201 Unix designs, these two provide the fundemental scheduling
 202 primitive within AltOS.</p>
 203 </li>
 204 <li>
 205 <p>Mutexes. As a locking primitive, mutexes are easier to
 206 use than semaphores, at least in my experience.</p>
 207 </li>
 208 <li>
 209 <p>Timers. Tasks can set an alarm which will abort any
 210 pending sleep, allowing operations to time-out instead of
 211 blocking forever.</p>
 212 </li>
 213 </ul>
 214 </div>
 215 <div class="paragraph">
 216 <p>The device drivers and other subsystems in AltOS are
 217 conventionally enabled by invoking their _init() function from
 218 the 'main' function before that calls
 219 ao_start_scheduler(). These functions initialize the pin
 220 assignments, add various commands to the command processor and
 221 may add tasks to the scheduler to handle the device. A typical
 222 main program, thus, looks like:</p>
 223 </div>
 224 <div class="literalblock">
 225 <div class="content">
 226 <pre>void
 227 main(void)
 228 {
 229         ao_clock_init();
 230
 231         /* Turn on the LED until the system is stable */
 232         ao_led_init(LEDS_AVAILABLE);
 233         ao_led_on(AO_LED_RED);
 234         ao_timer_init();
 235         ao_cmd_init();
 236         ao_usb_init();
 237         ao_monitor_init(AO_LED_GREEN, TRUE);
 238         ao_rssi_init(AO_LED_RED);
 239         ao_radio_init();
 240         ao_packet_slave_init();
 241         ao_packet_master_init();
 242 #if HAS_DBG
 243         ao_dbg_init();
 244 #endif
 245         ao_config_init();
 246         ao_start_scheduler();
 247 }</pre>
 248 </div>
 249 </div>
 250 <div class="paragraph">
 251 <p>As you can see, a long sequence of subsystems are initialized
 252 and then the scheduler is started.</p>
 253 </div>
 254 </div>
 255 </div>
 256 <div class="sect1">
 257 <h2 id="_altos_porting_layer">2. AltOS Porting Layer</h2>
 258 <div class="sectionbody">
 259 <div class="paragraph">
 260 <p>AltOS provides a CPU-independent interface to various common
 261 microcontroller subsystems, including GPIO pins, interrupts,
 262 SPI, I2C, USB and asynchronous serial interfaces. By making
 263 these CPU-independent, device drivers, generic OS and
 264 application code can all be written that work on any supported
 265 CPU. Many of the architecture abstraction interfaces are
 266 prefixed with ao_arch.</p>
 267 </div>
 268 <div class="sect2">
 269 <h3 id="_low_level_cpu_operations">2.1. Low-level CPU operations</h3>
 270 <div class="paragraph">
 271 <p>These primitive operations provide the abstraction needed to
 272 run the multi-tasking framework while providing reliable
 273 interrupt delivery.</p>
 274 </div>
 275 <div class="sect3">
 276 <h4 id="_ao_arch_block_interruptsao_arch_release_interrupts">2.1.1. ao_arch_block_interrupts/ao_arch_release_interrupts</h4>
 277 <div class="literalblock">
 278 <div class="content">
 279 <pre>static inline void
 280 ao_arch_block_interrupts(void);
 281
 282 static inline void
 283 ao_arch_release_interrupts(void);</pre>
 284 </div>
 285 </div>
 286 <div class="paragraph">
 287 <p>These disable/enable interrupt delivery, they may not
 288 discard any interrupts. Use these for sections of code that
 289 must be atomic with respect to any code run from an
 290 interrupt handler.</p>
 291 </div>
 292 </div>
 293 <div class="sect3">
 294 <h4 id="_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</h4>
 295 <div class="literalblock">
 296 <div class="content">
 297 <pre>static inline void
 298 ao_arch_save_regs(void);
 299
 300 static inline void
 301 ao_arch_save_stack(void);
 302
 303 static inline void
 304 ao_arch_restore_stack(void);</pre>
 305 </div>
 306 </div>
 307 <div class="paragraph">
 308 <p>These provide all of the support needed to switch
 309 between tasks.. ao_arch_save_regs must save all CPU
 310 registers to the current stack, including the
 311 interrupt enable state. ao_arch_save_stack records the
 312 current stack location in the current ao_task
 313 structure. ao_arch_restore_stack switches back to the
 314 saved stack, restores all registers and branches to
 315 the saved return address.</p>
 316 </div>
 317 </div>
 318 <div class="sect3">
 319 <h4 id="_ao_arch_wait_interupt">2.1.3. ao_arch_wait_interupt</h4>
 320 <div class="literalblock">
 321 <div class="content">
 322 <pre>#define ao_arch_wait_interrupt()</pre>
 323 </div>
 324 </div>
 325 <div class="paragraph">
 326 <p>This stops the CPU, leaving clocks and interrupts
 327 enabled. When an interrupt is received, this must wake up
 328 and handle the interrupt. ao_arch_wait_interrupt is entered
 329 with interrupts disabled to ensure that there is no gap
 330 between determining that no task wants to run and idling the
 331 CPU. It must sleep the CPU, process interrupts and then
 332 disable interrupts again. If the CPU doesn&#8217;t have any
 333 reduced power mode, this must at the least allow pending
 334 interrupts to be processed.</p>
 335 </div>
 336 </div>
 337 </div>
 338 <div class="sect2">
 339 <h3 id="_gpio_operations">2.2. GPIO operations</h3>
 340 <div class="paragraph">
 341 <p>These functions provide an abstract interface to configure and
 342 manipulate GPIO pins.</p>
 343 </div>
 344 <div class="sect3">
 345 <h4 id="_gpio_setup">2.2.1. GPIO setup</h4>
 346 <div class="paragraph">
 347 <p>These macros may be invoked at system
 348 initialization time to configure pins as
 349 needed for system operation. One tricky aspect
 350 is that some chips provide direct access to
 351 specific GPIO pins while others only provide
 352 access to a whole register full of pins. To
 353 support this, the GPIO macros provide both
 354 port+bit and pin arguments. Simply define the
 355 arguments needed for the target platform and
 356 leave the others undefined.</p>
 357 </div>
 358 <div class="sect4">
 359 <h5 id="_ao_enable_output">ao_enable_output</h5>
 360 <div class="literalblock">
 361 <div class="content">
 362 <pre>#define ao_enable_output(port, bit, pin, value)</pre>
 363 </div>
 364 </div>
 365 <div class="paragraph">
 366 <p>Set the specified port+bit (also called 'pin')
 367 for output, initializing to the specified
 368 value. The macro must avoid driving the pin
 369 with the opposite value if at all possible.</p>
 370 </div>
 371 </div>
 372 <div class="sect4">
 373 <h5 id="_ao_enable_input">ao_enable_input</h5>
 374 <div class="literalblock">
 375 <div class="content">
 376 <pre>#define ao_enable_input(port, bit, mode)</pre>
 377 </div>
 378 </div>
 379 <div class="paragraph">
 380 <p>Sets the specified port/bit to be an input
 381 pin. 'mode' is a combination of one or more of
 382 the following. Note that some platforms may
 383 not support the desired mode. In that case,
 384 the value will not be defined so that the
 385 program will fail to compile.</p>
 386 </div>
 387 <div class="ulist">
 388 <ul>
 389 <li>
 390 <p>AO_EXTI_MODE_PULL_UP. Apply a pull-up to the
 391 pin; a disconnected pin will read as 1.</p>
 392 </li>
 393 <li>
 394 <p>AO_EXTI_MODE_PULL_DOWN. Apply a pull-down to
 395 the pin; a disconnected pin will read as 0.</p>
 396 </li>
 397 <li>
 398 <p>0. Don&#8217;t apply either a pull-up or
 399 pull-down. A disconnected pin will read an
 400 undetermined value.</p>
 401 </li>
 402 </ul>
 403 </div>
 404 </div>
 405 </div>
 406 <div class="sect3">
 407 <h4 id="_reading_and_writing_gpio_pins">2.2.2. Reading and writing GPIO pins</h4>
 408 <div class="paragraph">
 409 <p>These macros read and write individual GPIO pins.</p>
 410 </div>
 411 <div class="sect4">
 412 <h5 id="_ao_gpio_set">ao_gpio_set</h5>
 413 <div class="literalblock">
 414 <div class="content">
 415 <pre>#define ao_gpio_set(port, bit, pin, value)</pre>
 416 </div>
 417 </div>
 418 <div class="paragraph">
 419 <p>Sets the specified port/bit or pin to
 420 the indicated value</p>
 421 </div>
 422 </div>
 423 <div class="sect4">
 424 <h5 id="_ao_gpio_get">ao_gpio_get</h5>
 425 <div class="literalblock">
 426 <div class="content">
 427 <pre>#define ao_gpio_get(port, bit, pin)</pre>
 428 </div>
 429 </div>
 430 <div class="paragraph">
 431 <p>Returns either 1 or 0 depending on
 432 whether the input to the pin is high
 433 or low.
 434 == Programming the 8051 with SDCC</p>
 435 </div>
 436 <div class="paragraph">
 437 <p>The 8051 is a primitive 8-bit processor, designed in the mists
 438 of time in as few transistors as possible. The architecture is
 439 highly irregular and includes several separate memory
 440 spaces. Furthermore, accessing stack variables is slow, and
 441 the stack itself is of limited size. While SDCC papers over
 442 the instruction set, it is not completely able to hide the
 443 memory architecture from the application designer.</p>
 444 </div>
 445 <div class="paragraph">
 446 <p>When built on other architectures, the various SDCC-specific
 447 symbols are #defined as empty strings so they don&#8217;t affect the
 448 compiler.</p>
 449 </div>
 450 </div>
 451 </div>
 452 </div>
 453 <div class="sect2">
 454 <h3 id="_8051_memory_spaces">2.3. 8051 memory spaces</h3>
 455 <div class="paragraph">
 456 <p>The <em>data/</em>xdata/__code memory spaces below were completely
 457 separate in the original 8051 design. In the cc1111, this
 458 isn&#8217;t true—they all live in a single unified 64kB address
 459 space, and so it&#8217;s possible to convert any address into a
 460 unique 16-bit address. SDCC doesn&#8217;t know this, and so a
 461 'global' address to SDCC consumes 3 bytes of memory, 1 byte as
 462 a tag indicating the memory space and 2 bytes of offset within
 463 that space. AltOS avoids these 3-byte addresses as much as
 464 possible; using them involves a function call per byte
 465 access. The result is that nearly every variable declaration
 466 is decorated with a memory space identifier which clutters the
 467 code but makes the resulting code far smaller and more
 468 efficient.</p>
 469 </div>
 470 <div class="sect3">
 471 <h4 id="_data">2.3.1. __data</h4>
 472 <div class="paragraph">
 473 <p>The 8051 can directly address these 128 bytes of
 474 memory. This makes them precious so they should be
 475 reserved for frequently addressed values. Oh, just to
 476 confuse things further, the 8 general registers in the
 477 CPU are actually stored in this memory space. There are
 478 magic instructions to 'bank switch' among 4 banks of
 479 these registers located at 0x00 - 0x1F. AltOS uses only
 480 the first bank at 0x00 - 0x07, leaving the other 24
 481 bytes available for other data.</p>
 482 </div>
 483 </div>
 484 <div class="sect3">
 485 <h4 id="_idata">2.3.2. __idata</h4>
 486 <div class="paragraph">
 487 <p>There are an additional 128 bytes of internal memory
 488 that share the same address space as __data but which
 489 cannot be directly addressed. The stack normally
 490 occupies this space and so AltOS doesn&#8217;t place any
 491 static storage here.</p>
 492 </div>
 493 </div>
 494 <div class="sect3">
 495 <h4 id="_xdata">2.3.3. __xdata</h4>
 496 <div class="paragraph">
 497 <p>This is additional general memory accessed through a
 498 single 16-bit address register. The CC1111F32 has 32kB
 499 of memory available here. Most program data should live
 500 in this memory space.</p>
 501 </div>
 502 </div>
 503 <div class="sect3">
 504 <h4 id="_pdata">2.3.4. __pdata</h4>
 505 <div class="paragraph">
 506 <p>This is an alias for the first 256 bytes of __xdata
 507 memory, but uses a shorter addressing mode with
 508 single global 8-bit value for the high 8 bits of the
 509 address and any of several 8-bit registers for the low 8
 510 bits. AltOS uses a few bits of this memory, it should
 511 probably use more.</p>
 512 </div>
 513 </div>
 514 <div class="sect3">
 515 <h4 id="_code">2.3.5. __code</h4>
 516 <div class="paragraph">
 517 <p>All executable code must live in this address space, but
 518 you can stick read-only data here too. It is addressed
 519 using the 16-bit address register and special 'code'
 520 access opcodes. Anything read-only should live in this space.</p>
 521 </div>
 522 </div>
 523 <div class="sect3">
 524 <h4 id="_bit">2.3.6. __bit</h4>
 525 <div class="paragraph">
 526 <p>The 8051 has 128 bits of bit-addressible memory that
 527 lives in the <em>data segment from 0x20 through
 528 0x2f. Special instructions access these bits
 529 in a single atomic operation. This isn&#8217;t so much a
 530 separate address space as a special addressing mode for
 531 a few bytes in the </em>data segment.</p>
 532 </div>
 533 </div>
 534 <div class="sect3">
 535 <h4 id="_sfr_sfr16_sfr32_sbit">2.3.7. <em>sfr, </em>sfr16, <em>sfr32, </em>sbit</h4>
 536 <div class="paragraph">
 537 <p>Access to physical registers in the device use this mode
 538 which declares the variable name, its type and the
 539 address it lives at. No memory is allocated for these
 540 variables.</p>
 541 </div>
 542 </div>
 543 </div>
 544 <div class="sect2">
 545 <h3 id="_function_calls_on_the_8051">2.4. Function calls on the 8051</h3>
 546 <div class="paragraph">
 547 <p>Because stack addressing is expensive, and stack space
 548 limited, the default function call declaration in SDCC
 549 allocates all parameters and local variables in static global
 550 memory. Just like fortran. This makes these functions
 551 non-reentrant, and also consume space for parameters and
 552 locals even when they are not running. The benefit is smaller
 553 code and faster execution.</p>
 554 </div>
 555 <div class="sect3">
 556 <h4 id="_reentrant_functions">2.4.1. __reentrant functions</h4>
 557 <div class="paragraph">
 558 <p>All functions which are re-entrant, either due to recursion
 559 or due to a potential context switch while executing, should
 560 be marked as __reentrant so that their parameters and local
 561 variables get allocated on the stack. This ensures that
 562 these values are not overwritten by another invocation of
 563 the function.</p>
 564 </div>
 565 <div class="paragraph">
 566 <p>Functions which use significant amounts of space for
 567 arguments and/or local variables and which are not often
 568 invoked can also be marked as __reentrant. The resulting
 569 code will be larger, but the savings in memory are
 570 frequently worthwhile.</p>
 571 </div>
 572 </div>
 573 <div class="sect3">
 574 <h4 id="_non_reentrant_functions">2.4.2. Non __reentrant functions</h4>
 575 <div class="paragraph">
 576 <p>All parameters and locals in non-reentrant functions can
 577 have data space decoration so that they are allocated in
 578 <em>xdata, </em>pdata or <em>data space as desired. This can avoid
 579 consuming </em>data space for infrequently used variables in
 580 frequently used functions.</p>
 581 </div>
 582 <div class="paragraph">
 583 <p>All library functions called by SDCC, including functions
 584 for multiplying and dividing large data types, are
 585 non-reentrant. Because of this, interrupt handlers must not
 586 invoke any library functions, including the multiply and
 587 divide code.</p>
 588 </div>
 589 </div>
 590 <div class="sect3">
 591 <h4 id="_interrupt_functions">2.4.3. __interrupt functions</h4>
 592 <div class="paragraph">
 593 <p>Interrupt functions are declared with with an __interrupt
 594 decoration that includes the interrupt number. SDCC saves
 595 and restores all of the registers in these functions and
 596 uses the 'reti' instruction at the end so that they operate
 597 as stand-alone interrupt handlers. Interrupt functions may
 598 call the ao_wakeup function to wake AltOS tasks.</p>
 599 </div>
 600 </div>
 601 <div class="sect3">
 602 <h4 id="_critical_functions_and_statements">2.4.4. __critical functions and statements</h4>
 603 <div class="paragraph">
 604 <p>SDCC has built-in support for suspending interrupts during
 605 critical code. Functions marked as <em>critical will have
 606 interrupts suspended for the whole period of
 607 execution. Individual statements may also be marked as
 608 </em>critical which blocks interrupts during the execution of
 609 that statement. Keeping critical sections as short as
 610 possible is key to ensuring that interrupts are handled as
 611 quickly as possible. AltOS doesn&#8217;t use this form in shared
 612 code as other compilers wouldn&#8217;t know what to do. Use
 613 ao_arch_block_interrupts and ao_arch_release_interrupts instead.</p>
 614 </div>
 615 </div>
 616 </div>
 617 </div>
 618 </div>
 619 <div class="sect1">
 620 <h2 id="_task_functions">3. Task functions</h2>
 621 <div class="sectionbody">
 622 <div class="paragraph">
 623 <p>This chapter documents how to create, destroy and schedule
 624 AltOS tasks.</p>
 625 </div>
 626 <div class="sect2">
 627 <h3 id="_ao_add_task">3.1. ao_add_task</h3>
 628 <div class="literalblock">
 629 <div class="content">
 630 <pre>void
 631 ao_add_task(__xdata struct ao_task * task,
 632             void (*start)(void),
 633             __code char *name);</pre>
 634 </div>
 635 </div>
 636 <div class="paragraph">
 637 <p>This initializes the statically allocated task structure,
 638 assigns a name to it (not used for anything but the task
 639 display), and the start address. It does not switch to the
 640 new task. 'start' must not ever return; there is no place
 641 to return to.</p>
 642 </div>
 643 </div>
 644 <div class="sect2">
 645 <h3 id="_ao_exit">3.2. ao_exit</h3>
 646 <div class="literalblock">
 647 <div class="content">
 648 <pre>void
 649 ao_exit(void)</pre>
 650 </div>
 651 </div>
 652 <div class="paragraph">
 653 <p>This terminates the current task.</p>
 654 </div>
 655 </div>
 656 <div class="sect2">
 657 <h3 id="_ao_sleep">3.3. ao_sleep</h3>
 658 <div class="literalblock">
 659 <div class="content">
 660 <pre>void
 661 ao_sleep(__xdata void *wchan)</pre>
 662 </div>
 663 </div>
 664 <div class="paragraph">
 665 <p>This suspends the current task until 'wchan' is signaled
 666 by ao_wakeup, or until the timeout, set by ao_alarm,
 667 fires. If 'wchan' is signaled, ao_sleep returns 0, otherwise
 668 it returns 1. This is the only way to switch to another task.</p>
 669 </div>
 670 <div class="paragraph">
 671 <p>Because ao_wakeup wakes every task waiting on a particular
 672 location, ao_sleep should be used in a loop that first checks
 673 the desired condition, blocks in ao_sleep and then rechecks
 674 until the condition is satisfied. If the location may be
 675 signaled from an interrupt handler, the code will need to
 676 block interrupts around the block of code. Here&#8217;s a complete
 677 example:</p>
 678 </div>
 679 <div class="literalblock">
 680 <div class="content">
 681 <pre>ao_arch_block_interrupts();
 682 while (!ao_radio_done)
 683         ao_sleep(&amp;amp;ao_radio_done);
 684 ao_arch_release_interrupts();</pre>
 685 </div>
 686 </div>
 687 </div>
 688 <div class="sect2">
 689 <h3 id="_ao_wakeup">3.4. ao_wakeup</h3>
 690 <div class="literalblock">
 691 <div class="content">
 692 <pre>void
 693 ao_wakeup(__xdata void *wchan)</pre>
 694 </div>
 695 </div>
 696 <div class="paragraph">
 697 <p>Wake all tasks blocked on 'wchan'. This makes them
 698 available to be run again, but does not actually switch
 699 to another task. Here&#8217;s an example of using this:</p>
 700 </div>
 701 <div class="literalblock">
 702 <div class="content">
 703 <pre>if (RFIF &amp;amp; RFIF_IM_DONE) {
 704         ao_radio_done = 1;
 705         ao_wakeup(&amp;amp;ao_radio_done);
 706         RFIF &amp;amp;= ~RFIF_IM_DONE;
 707 }</pre>
 708 </div>
 709 </div>
 710 <div class="paragraph">
 711 <p>Note that this need not block interrupts as the
 712 ao_sleep block can only be run from normal mode, and
 713 so this sequence can never be interrupted with
 714 execution of the other sequence.</p>
 715 </div>
 716 </div>
 717 <div class="sect2">
 718 <h3 id="_ao_alarm">3.5. ao_alarm</h3>
 719 <div class="literalblock">
 720 <div class="content">
 721 <pre>void
 722 ao_alarm(uint16_t delay);
 723
 724 void
 725 ao_clear_alarm(void);</pre>
 726 </div>
 727 </div>
 728 <div class="paragraph">
 729 <p>Schedules an alarm to fire in at least 'delay'
 730 ticks. If the task is asleep when the alarm fires, it
 731 will wakeup and ao_sleep will return 1. ao_clear_alarm
 732 resets any pending alarm so that it doesn&#8217;t fire at
 733 some arbitrary point in the future.</p>
 734 </div>
 735 <div class="literalblock">
 736 <div class="content">
 737 <pre>ao_alarm(ao_packet_master_delay);
 738 ao_arch_block_interrupts();
 739 while (!ao_radio_dma_done)
 740 if (ao_sleep(&amp;amp;ao_radio_dma_done) != 0)
 741 ao_radio_abort();
 742 ao_arch_release_interrupts();
 743 ao_clear_alarm();</pre>
 744 </div>
 745 </div>
 746 <div class="paragraph">
 747 <p>In this example, a timeout is set before waiting for
 748 incoming radio data. If no data is received before the
 749 timeout fires, ao_sleep will return 1 and then this
 750 code will abort the radio receive operation.</p>
 751 </div>
 752 </div>
 753 <div class="sect2">
 754 <h3 id="_ao_start_scheduler">3.6. ao_start_scheduler</h3>
 755 <div class="literalblock">
 756 <div class="content">
 757 <pre>void
 758 ao_start_scheduler(void);</pre>
 759 </div>
 760 </div>
 761 <div class="paragraph">
 762 <p>This is called from 'main' when the system is all
 763 initialized and ready to run. It will not return.</p>
 764 </div>
 765 </div>
 766 <div class="sect2">
 767 <h3 id="_ao_clock_init">3.7. ao_clock_init</h3>
 768 <div class="literalblock">
 769 <div class="content">
 770 <pre>void
 771 ao_clock_init(void);</pre>
 772 </div>
 773 </div>
 774 <div class="paragraph">
 775 <p>This initializes the main CPU clock and switches to it.</p>
 776 </div>
 777 </div>
 778 </div>
 779 </div>
 780 <div class="sect1">
 781 <h2 id="_timer_functions">4. Timer Functions</h2>
 782 <div class="sectionbody">
 783 <div class="paragraph">
 784 <p>AltOS sets up one of the CPU timers to run at 100Hz and
 785 exposes this tick as the fundemental unit of time. At each
 786 interrupt, AltOS increments the counter, and schedules any tasks
 787 waiting for that time to pass, then fires off the sensors to
 788 collect current data readings. Doing this from the ISR ensures
 789 that the values are sampled at a regular rate, independent
 790 of any scheduling jitter.</p>
 791 </div>
 792 <div class="sect2">
 793 <h3 id="_ao_time">4.1. ao_time</h3>
 794 <div class="literalblock">
 795 <div class="content">
 796 <pre>uint16_t
 797 ao_time(void)</pre>
 798 </div>
 799 </div>
 800 <div class="paragraph">
 801 <p>Returns the current system tick count. Note that this is
 802 only a 16 bit value, and so it wraps every 655.36 seconds.</p>
 803 </div>
 804 </div>
 805 <div class="sect2">
 806 <h3 id="_ao_delay">4.2. ao_delay</h3>
 807 <div class="literalblock">
 808 <div class="content">
 809 <pre>void
 810 ao_delay(uint16_t ticks);</pre>
 811 </div>
 812 </div>
 813 <div class="paragraph">
 814 <p>Suspend the current task for at least 'ticks' clock units.</p>
 815 </div>
 816 </div>
 817 <div class="sect2">
 818 <h3 id="_ao_timer_set_adc_interval">4.3. ao_timer_set_adc_interval</h3>
 819 <div class="literalblock">
 820 <div class="content">
 821 <pre>void
 822 ao_timer_set_adc_interval(uint8_t interval);</pre>
 823 </div>
 824 </div>
 825 <div class="paragraph">
 826 <p>This sets the number of ticks between ADC samples. If set
 827 to 0, no ADC samples are generated. AltOS uses this to
 828 slow down the ADC sampling rate to save power.</p>
 829 </div>
 830 </div>
 831 <div class="sect2">
 832 <h3 id="_ao_timer_init">4.4. ao_timer_init</h3>
 833 <div class="literalblock">
 834 <div class="content">
 835 <pre>void
 836 ao_timer_init(void)</pre>
 837 </div>
 838 </div>
 839 <div class="paragraph">
 840 <p>This turns on the 100Hz tick. It is required for any of the
 841 time-based functions to work. It should be called by 'main'
 842 before ao_start_scheduler.</p>
 843 </div>
 844 </div>
 845 </div>
 846 </div>
 847 <div class="sect1">
 848 <h2 id="_altos_mutexes">5. AltOS Mutexes</h2>
 849 <div class="sectionbody">
 850 <div class="paragraph">
 851 <p>AltOS provides mutexes as a basic synchronization primitive. Each
 852 mutexes is simply a byte of memory which holds 0 when the mutex
 853 is free or the task id of the owning task when the mutex is
 854 owned. Mutex calls are checked—attempting to acquire a mutex
 855 already held by the current task or releasing a mutex not held
 856 by the current task will both cause a panic.</p>
 857 </div>
 858 <div class="sect2">
 859 <h3 id="_ao_mutex_get">5.1. ao_mutex_get</h3>
 860 <div class="literalblock">
 861 <div class="content">
 862 <pre>void
 863 ao_mutex_get(__xdata uint8_t *mutex);</pre>
 864 </div>
 865 </div>
 866 <div class="paragraph">
 867 <p>Acquires the specified mutex, blocking if the mutex is
 868 owned by another task.</p>
 869 </div>
 870 </div>
 871 <div class="sect2">
 872 <h3 id="_ao_mutex_put">5.2. ao_mutex_put</h3>
 873 <div class="literalblock">
 874 <div class="content">
 875 <pre>void
 876 ao_mutex_put(__xdata uint8_t *mutex);</pre>
 877 </div>
 878 </div>
 879 <div class="paragraph">
 880 <p>Releases the specified mutex, waking up all tasks waiting
 881 for it.</p>
 882 </div>
 883 </div>
 884 </div>
 885 </div>
 886 <div class="sect1">
 887 <h2 id="_dma_engine">6. DMA engine</h2>
 888 <div class="sectionbody">
 889 <div class="paragraph">
 890 <p>The CC1111 and STM32L both contain a useful bit of extra
 891 hardware in the form of a number of programmable DMA
 892 engines. They can be configured to copy data in memory, or
 893 between memory and devices (or even between two devices). AltOS
 894 exposes a general interface to this hardware and uses it to
 895 handle both internal and external devices.</p>
 896 </div>
 897 <div class="paragraph">
 898 <p>Because the CC1111 and STM32L DMA engines are different, the
 899 interface to them is also different. As the DMA engines are
 900 currently used to implement platform-specific drivers, this
 901 isn&#8217;t yet a problem.</p>
 902 </div>
 903 <div class="paragraph">
 904 <p>Code using a DMA engine should allocate one at startup
 905 time. There is no provision to free them, and if you run out,
 906 AltOS will simply panic.</p>
 907 </div>
 908 <div class="paragraph">
 909 <p>During operation, the DMA engine is initialized with the
 910 transfer parameters. Then it is started, at which point it
 911 awaits a suitable event to start copying data. When copying data
 912 from hardware to memory, that trigger event is supplied by the
 913 hardware device. When copying data from memory to hardware, the
 914 transfer is usually initiated by software.</p>
 915 </div>
 916 <div class="sect2">
 917 <h3 id="_cc1111_dma_engine">6.1. CC1111 DMA Engine</h3>
 918 <div class="sect3">
 919 <h4 id="_ao_dma_alloc">6.1.1. ao_dma_alloc</h4>
 920 <div class="literalblock">
 921 <div class="content">
 922 <pre>uint8_t
 923 ao_dma_alloc(__xdata uint8_t *done)</pre>
 924 </div>
 925 </div>
 926 <div class="paragraph">
 927 <p>Allocate a DMA engine, returning the
 928 identifier.  'done' is cleared when the DMA is
 929 started, and then receives the AO_DMA_DONE bit
 930 on a successful transfer or the AO_DMA_ABORTED
 931 bit if ao_dma_abort was called. Note that it
 932 is possible to get both bits if the transfer
 933 was aborted after it had finished.</p>
 934 </div>
 935 </div>
 936 <div class="sect3">
 937 <h4 id="_ao_dma_set_transfer">6.1.2. ao_dma_set_transfer</h4>
 938 <div class="literalblock">
 939 <div class="content">
 940 <pre>void
 941 ao_dma_set_transfer(uint8_t id,
 942 void __xdata *srcaddr,
 943 void __xdata *dstaddr,
 944 uint16_t count,
 945 uint8_t cfg0,
 946 uint8_t cfg1)</pre>
 947 </div>
 948 </div>
 949 <div class="paragraph">
 950 <p>Initializes the specified dma engine to copy
 951 data from 'srcaddr' to 'dstaddr' for 'count'
 952 units. cfg0 and cfg1 are values directly out
 953 of the CC1111 documentation and tell the DMA
 954 engine what the transfer unit size, direction
 955 and step are.</p>
 956 </div>
 957 </div>
 958 <div class="sect3">
 959 <h4 id="_ao_dma_start">6.1.3. ao_dma_start</h4>
 960 <div class="literalblock">
 961 <div class="content">
 962 <pre>void
 963 ao_dma_start(uint8_t id);</pre>
 964 </div>
 965 </div>
 966 <div class="paragraph">
 967 <p>Arm the specified DMA engine and await a
 968 signal from either hardware or software to
 969 start transferring data.</p>
 970 </div>
 971 </div>
 972 <div class="sect3">
 973 <h4 id="_ao_dma_trigger">6.1.4. ao_dma_trigger</h4>
 974 <div class="literalblock">
 975 <div class="content">
 976 <pre>void
 977 ao_dma_trigger(uint8_t id)</pre>
 978 </div>
 979 </div>
 980 <div class="paragraph">
 981 <p>Trigger the specified DMA engine to start
 982 copying data.</p>
 983 </div>
 984 </div>
 985 <div class="sect3">
 986 <h4 id="_ao_dma_abort">6.1.5. ao_dma_abort</h4>
 987 <div class="literalblock">
 988 <div class="content">
 989 <pre>void
 990 ao_dma_abort(uint8_t id)</pre>
 991 </div>
 992 </div>
 993 <div class="paragraph">
 994 <p>Terminate any in-progress DMA transaction,
 995 marking its 'done' variable with the
 996 AO_DMA_ABORTED bit.</p>
 997 </div>
 998 </div>
 999 </div>
1000 <div class="sect2">
1001 <h3 id="_stm32l_dma_engine">6.2. STM32L DMA Engine</h3>
1002 <div class="sect3">
1003 <h4 id="_ao_dma_alloc_2">6.2.1. ao_dma_alloc</h4>
1004 <div class="literalblock">
1005 <div class="content">
1006 <pre>uint8_t ao_dma_done[];
1007
1008 void
1009 ao_dma_alloc(uint8_t index);</pre>
1010 </div>
1011 </div>
1012 <div class="paragraph">
1013 <p>Reserve a DMA engine for exclusive use by one
1014 driver.</p>
1015 </div>
1016 </div>
1017 <div class="sect3">
1018 <h4 id="_ao_dma_set_transfer_2">6.2.2. ao_dma_set_transfer</h4>
1019 <div class="literalblock">
1020 <div class="content">
1021 <pre>void
1022 ao_dma_set_transfer(uint8_t id,
1023 void *peripheral,
1024 void *memory,
1025 uint16_t count,
1026 uint32_t ccr);</pre>
1027 </div>
1028 </div>
1029 <div class="paragraph">
1030 <p>Initializes the specified dma engine to copy
1031 data between 'peripheral' and 'memory' for
1032 'count' units. 'ccr' is a value directly out
1033 of the STM32L documentation and tells the DMA
1034 engine what the transfer unit size, direction
1035 and step are.</p>
1036 </div>
1037 </div>
1038 <div class="sect3">
1039 <h4 id="_ao_dma_set_isr">6.2.3. ao_dma_set_isr</h4>
1040 <div class="literalblock">
1041 <div class="content">
1042 <pre>void
1043 ao_dma_set_isr(uint8_t index, void (*isr)(int))</pre>
1044 </div>
1045 </div>
1046 <div class="paragraph">
1047 <p>This sets a function to be called when the DMA
1048 transfer completes in lieu of setting the
1049 ao_dma_done bits. Use this when some work
1050 needs to be done when the DMA finishes that
1051 cannot wait until user space resumes.</p>
1052 </div>
1053 </div>
1054 <div class="sect3">
1055 <h4 id="_ao_dma_start_2">6.2.4. ao_dma_start</h4>
1056 <div class="literalblock">
1057 <div class="content">
1058 <pre>void
1059 ao_dma_start(uint8_t id);</pre>
1060 </div>
1061 </div>
1062 <div class="paragraph">
1063 <p>Arm the specified DMA engine and await a
1064 signal from either hardware or software to
1065 start transferring data.  'ao_dma_done[index]'
1066 is cleared when the DMA is started, and then
1067 receives the AO_DMA_DONE bit on a successful
1068 transfer or the AO_DMA_ABORTED bit if
1069 ao_dma_abort was called. Note that it is
1070 possible to get both bits if the transfer was
1071 aborted after it had finished.</p>
1072 </div>
1073 </div>
1074 <div class="sect3">
1075 <h4 id="_ao_dma_done_transfer">6.2.5. ao_dma_done_transfer</h4>
1076 <div class="literalblock">
1077 <div class="content">
1078 <pre>void
1079 ao_dma_done_transfer(uint8_t id);</pre>
1080 </div>
1081 </div>
1082 <div class="paragraph">
1083 <p>Signals that a specific DMA engine is done
1084 being used. This allows multiple drivers to
1085 use the same DMA engine safely.</p>
1086 </div>
1087 </div>
1088 <div class="sect3">
1089 <h4 id="_ao_dma_abort_2">6.2.6. ao_dma_abort</h4>
1090 <div class="literalblock">
1091 <div class="content">
1092 <pre>void
1093 ao_dma_abort(uint8_t id)</pre>
1094 </div>
1095 </div>
1096 <div class="paragraph">
1097 <p>Terminate any in-progress DMA transaction,
1098 marking its 'done' variable with the
1099 AO_DMA_ABORTED bit.</p>
1100 </div>
1101 </div>
1102 </div>
1103 </div>
1104 </div>
1105 <div class="sect1">
1106 <h2 id="_stdio_interface">7. Stdio interface</h2>
1107 <div class="sectionbody">
1108 <div class="paragraph">
1109 <p>AltOS offers a stdio interface over USB, serial and the RF
1110 packet link. This provides for control of the device locally or
1111 remotely. This is hooked up to the stdio functions by providing
1112 the standard putchar/getchar/flush functions. These
1113 automatically multiplex the available communication channels;
1114 output is always delivered to the channel which provided the
1115 most recent input.</p>
1116 </div>
1117 <div class="sect2">
1118 <h3 id="_putchar">7.1. putchar</h3>
1119 <div class="literalblock">
1120 <div class="content">
1121 <pre>void
1122 putchar(char c)</pre>
1123 </div>
1124 </div>
1125 <div class="paragraph">
1126 <p>Delivers a single character to the current console
1127 device.</p>
1128 </div>
1129 </div>
1130 <div class="sect2">
1131 <h3 id="_getchar">7.2. getchar</h3>
1132 <div class="literalblock">
1133 <div class="content">
1134 <pre>char
1135 getchar(void)</pre>
1136 </div>
1137 </div>
1138 <div class="paragraph">
1139 <p>Reads a single character from any of the available
1140 console devices. The current console device is set to
1141 that which delivered this character. This blocks until
1142 a character is available.</p>
1143 </div>
1144 </div>
1145 <div class="sect2">
1146 <h3 id="_flush">7.3. flush</h3>
1147 <div class="literalblock">
1148 <div class="content">
1149 <pre>void
1150 flush(void)</pre>
1151 </div>
1152 </div>
1153 <div class="paragraph">
1154 <p>Flushes the current console device output buffer. Any
1155 pending characters will be delivered to the target device.</p>
1156 </div>
1157 </div>
1158 <div class="sect2">
1159 <h3 id="_ao_add_stdio">7.4. ao_add_stdio</h3>
1160 <div class="literalblock">
1161 <div class="content">
1162 <pre>void
1163 ao_add_stdio(char (*pollchar)(void),
1164 void (*putchar)(char),
1165 void (*flush)(void))</pre>
1166 </div>
1167 </div>
1168 <div class="paragraph">
1169 <p>This adds another console device to the available
1170 list.</p>
1171 </div>
1172 <div class="paragraph">
1173 <p>'pollchar' returns either an available character or
1174 AO_READ_AGAIN if none is available. Significantly, it does
1175 not block. The device driver must set 'ao_stdin_ready' to
1176 1 and call ao_wakeup(&amp;ao_stdin_ready) when it receives
1177 input to tell getchar that more data is available, at
1178 which point 'pollchar' will be called again.</p>
1179 </div>
1180 <div class="paragraph">
1181 <p>'putchar' queues a character for output, flushing if the output buffer is
1182 full. It may block in this case.</p>
1183 </div>
1184 <div class="paragraph">
1185 <p>'flush' forces the output buffer to be flushed. It may
1186 block until the buffer is delivered, but it is not
1187 required to do so.</p>
1188 </div>
1189 </div>
1190 </div>
1191 </div>
1192 <div class="sect1">
1193 <h2 id="_command_line_interface">8. Command line interface</h2>
1194 <div class="sectionbody">
1195 <div class="paragraph">
1196 <p>AltOS includes a simple command line parser which is hooked up
1197 to the stdio interfaces permitting remote control of the
1198 device over USB, serial or the RF link as desired. Each
1199 command uses a single character to invoke it, the remaining
1200 characters on the line are available as parameters to the
1201 command.</p>
1202 </div>
1203 <div class="sect2">
1204 <h3 id="_ao_cmd_register">8.1. ao_cmd_register</h3>
1205 <div class="literalblock">
1206 <div class="content">
1207 <pre>void
1208 ao_cmd_register(__code struct ao_cmds *cmds)</pre>
1209 </div>
1210 </div>
1211 <div class="paragraph">
1212 <p>This registers a set of commands with the command
1213 parser. There is a fixed limit on the number of command
1214 sets, the system will panic if too many are registered.
1215 Each command is defined by a struct ao_cmds entry:</p>
1216 </div>
1217 <div class="literalblock">
1218 <div class="content">
1219 <pre>struct ao_cmds {
1220         char            cmd;
1221         void            (*func)(void);
1222         const char      *help;
1223 };</pre>
1224 </div>
1225 </div>
1226 <div class="paragraph">
1227 <p>'cmd' is the character naming the command. 'func' is the
1228 function to invoke and 'help' is a string displayed by the
1229 '?' command. Syntax errors found while executing 'func'
1230 should be indicated by modifying the global ao_cmd_status
1231 variable with one of the following values:</p>
1232 </div>
1233 <div class="dlist">
1234 <dl>
1235 <dt class="hdlist1">ao_cmd_success</dt>
1236 <dd>
1237 <p>The command was parsed successfully. There is no need
1238 to assign this value, it is the default.</p>
1239 </dd>
1240 <dt class="hdlist1">ao_cmd_lex_error</dt>
1241 <dd>
1242 <p>A token in the line was invalid, such as a number
1243 containing invalid characters. The low-level lexing
1244 functions already assign this value as needed.</p>
1245 </dd>
1246 <dt class="hdlist1">ao_syntax_error</dt>
1247 <dd>
1248 <p>The command line is invalid for some reason other than
1249 invalid tokens.</p>
1250 </dd>
1251 </dl>
1252 </div>
1253 </div>
1254 <div class="sect2">
1255 <h3 id="_ao_cmd_lex">8.2. ao_cmd_lex</h3>
1256 <div class="literalblock">
1257 <div class="content">
1258 <pre>void
1259 ao_cmd_lex(void);</pre>
1260 </div>
1261 </div>
1262 <div class="paragraph">
1263 <p>This gets the next character out of the command line
1264 buffer and sticks it into ao_cmd_lex_c. At the end of
1265 the line, ao_cmd_lex_c will get a newline ('\n')
1266 character.</p>
1267 </div>
1268 </div>
1269 <div class="sect2">
1270 <h3 id="_ao_cmd_put16">8.3. ao_cmd_put16</h3>
1271 <div class="literalblock">
1272 <div class="content">
1273 <pre>void
1274 ao_cmd_put16(uint16_t v);</pre>
1275 </div>
1276 </div>
1277 <div class="paragraph">
1278 <p>Writes 'v' as four hexadecimal characters.</p>
1279 </div>
1280 </div>
1281 <div class="sect2">
1282 <h3 id="_ao_cmd_put8">8.4. ao_cmd_put8</h3>
1283 <div class="literalblock">
1284 <div class="content">
1285 <pre>void
1286 ao_cmd_put8(uint8_t v);</pre>
1287 </div>
1288 </div>
1289 <div class="paragraph">
1290 <p>Writes 'v' as two hexadecimal characters.</p>
1291 </div>
1292 </div>
1293 <div class="sect2">
1294 <h3 id="_ao_cmd_white">8.5. ao_cmd_white</h3>
1295 <div class="literalblock">
1296 <div class="content">
1297 <pre>void
1298 ao_cmd_white(void)</pre>
1299 </div>
1300 </div>
1301 <div class="paragraph">
1302 <p>This skips whitespace by calling ao_cmd_lex while
1303 ao_cmd_lex_c is either a space or tab. It does not
1304 skip any characters if ao_cmd_lex_c already non-white.</p>
1305 </div>
1306 </div>
1307 <div class="sect2">
1308 <h3 id="_ao_cmd_hex">8.6. ao_cmd_hex</h3>
1309 <div class="literalblock">
1310 <div class="content">
1311 <pre>void
1312 ao_cmd_hex(void)</pre>
1313 </div>
1314 </div>
1315 <div class="paragraph">
1316 <p>This reads a 16-bit hexadecimal value from the command
1317 line with optional leading whitespace. The resulting
1318 value is stored in ao_cmd_lex_i;</p>
1319 </div>
1320 </div>
1321 <div class="sect2">
1322 <h3 id="_ao_cmd_decimal">8.7. ao_cmd_decimal</h3>
1323 <div class="literalblock">
1324 <div class="content">
1325 <pre>void
1326 ao_cmd_decimal(void)</pre>
1327 </div>
1328 </div>
1329 <div class="paragraph">
1330 <p>This reads a 32-bit decimal value from the command
1331 line with optional leading whitespace. The resulting
1332 value is stored in ao_cmd_lex_u32 and the low 16 bits
1333 are stored in ao_cmd_lex_i;</p>
1334 </div>
1335 </div>
1336 <div class="sect2">
1337 <h3 id="_ao_match_word">8.8. ao_match_word</h3>
1338 <div class="literalblock">
1339 <div class="content">
1340 <pre>uint8_t
1341 ao_match_word(__code char *word)</pre>
1342 </div>
1343 </div>
1344 <div class="paragraph">
1345 <p>This checks to make sure that 'word' occurs on the
1346 command line. It does not skip leading white space. If
1347 'word' is found, then 1 is returned. Otherwise,
1348 ao_cmd_status is set to ao_cmd_syntax_error and 0 is
1349 returned.</p>
1350 </div>
1351 </div>
1352 <div class="sect2">
1353 <h3 id="_ao_cmd_init">8.9. ao_cmd_init</h3>
1354 <div class="literalblock">
1355 <div class="content">
1356 <pre>void
1357 ao_cmd_init(void</pre>
1358 </div>
1359 </div>
1360 <div class="paragraph">
1361 <p>Initializes the command system, setting up the
1362 built-in commands and adding a task to run the command
1363 processing loop. It should be called by 'main' before
1364 ao_start_scheduler.</p>
1365 </div>
1366 </div>
1367 </div>
1368 </div>
1369 <div class="sect1">
1370 <h2 id="_usb_target_device">9. USB target device</h2>
1371 <div class="sectionbody">
1372 <div class="paragraph">
1373 <p>AltOS contains a full-speed USB target device driver. It can
1374 be programmed to offer any kind of USB target, but to simplify
1375 interactions with a variety of operating systems, AltOS
1376 provides only a single target device profile, that of a USB
1377 modem which has native drivers for Linux, Windows and Mac OS
1378 X. It would be easy to change the code to provide an alternate
1379 target device if necessary.</p>
1380 </div>
1381 <div class="paragraph">
1382 <p>To the rest of the system, the USB device looks like a simple
1383 two-way byte stream. It can be hooked into the command line
1384 interface if desired, offering control of the device over the
1385 USB link. Alternatively, the functions can be accessed
1386 directly to provide for USB-specific I/O.</p>
1387 </div>
1388 <div class="sect2">
1389 <h3 id="_ao_usb_flush">9.1. ao_usb_flush</h3>
1390 <div class="literalblock">
1391 <div class="content">
1392 <pre>void
1393 ao_usb_flush(void);</pre>
1394 </div>
1395 </div>
1396 <div class="paragraph">
1397 <p>Flushes any pending USB output. This queues an 'IN'
1398 packet to be delivered to the USB host if there is
1399 pending data, or if the last IN packet was full to
1400 indicate to the host that there isn&#8217;t any more pending
1401 data available.</p>
1402 </div>
1403 </div>
1404 <div class="sect2">
1405 <h3 id="_ao_usb_putchar">9.2. ao_usb_putchar</h3>
1406 <div class="literalblock">
1407 <div class="content">
1408 <pre>void
1409 ao_usb_putchar(char c);</pre>
1410 </div>
1411 </div>
1412 <div class="paragraph">
1413 <p>If there is a pending 'IN' packet awaiting delivery to
1414 the host, this blocks until that has been
1415 fetched. Then, this adds a byte to the pending IN
1416 packet for delivery to the USB host. If the USB packet
1417 is full, this queues the 'IN' packet for delivery.</p>
1418 </div>
1419 </div>
1420 <div class="sect2">
1421 <h3 id="_ao_usb_pollchar">9.3. ao_usb_pollchar</h3>
1422 <div class="literalblock">
1423 <div class="content">
1424 <pre>char
1425 ao_usb_pollchar(void);</pre>
1426 </div>
1427 </div>
1428 <div class="paragraph">
1429 <p>If there are no characters remaining in the last 'OUT'
1430 packet received, this returns
1431 AO_READ_AGAIN. Otherwise, it returns the next
1432 character, reporting to the host that it is ready for
1433 more data when the last character is gone.</p>
1434 </div>
1435 </div>
1436 <div class="sect2">
1437 <h3 id="_ao_usb_getchar">9.4. ao_usb_getchar</h3>
1438 <div class="literalblock">
1439 <div class="content">
1440 <pre>char
1441 ao_usb_getchar(void);</pre>
1442 </div>
1443 </div>
1444 <div class="paragraph">
1445 <p>This uses ao_pollchar to receive the next character,
1446 blocking while ao_pollchar returns AO_READ_AGAIN.</p>
1447 </div>
1448 </div>
1449 <div class="sect2">
1450 <h3 id="_ao_usb_disable">9.5. ao_usb_disable</h3>
1451 <div class="literalblock">
1452 <div class="content">
1453 <pre>void
1454 ao_usb_disable(void);</pre>
1455 </div>
1456 </div>
1457 <div class="paragraph">
1458 <p>This turns off the USB controller. It will no longer
1459 respond to host requests, nor return
1460 characters. Calling any of the i/o routines while the
1461 USB device is disabled is undefined, and likely to
1462 break things. Disabling the USB device when not needed
1463 saves power.</p>
1464 </div>
1465 <div class="paragraph">
1466 <p>Note that neither TeleDongle v0.2 nor TeleMetrum v1
1467 are able to signal to the USB host that they have
1468 disconnected, so after disabling the USB device, it&#8217;s
1469 likely that the cable will need to be disconnected and
1470 reconnected before it will work again.</p>
1471 </div>
1472 </div>
1473 <div class="sect2">
1474 <h3 id="_ao_usb_enable">9.6. ao_usb_enable</h3>
1475 <div class="literalblock">
1476 <div class="content">
1477 <pre>void
1478 ao_usb_enable(void);</pre>
1479 </div>
1480 </div>
1481 <div class="paragraph">
1482 <p>This turns the USB controller on again after it has
1483 been disabled. See the note above about needing to
1484 physically remove and re-insert the cable to get the
1485 host to re-initialize the USB link.</p>
1486 </div>
1487 </div>
1488 <div class="sect2">
1489 <h3 id="_ao_usb_init">9.7. ao_usb_init</h3>
1490 <div class="literalblock">
1491 <div class="content">
1492 <pre>void
1493 ao_usb_init(void);</pre>
1494 </div>
1495 </div>
1496 <div class="paragraph">
1497 <p>This turns the USB controller on, adds a task to
1498 handle the control end point and adds the usb I/O
1499 functions to the stdio system. Call this from main
1500 before ao_start_scheduler.</p>
1501 </div>
1502 </div>
1503 </div>
1504 </div>
1505 <div class="sect1">
1506 <h2 id="_serial_peripherals">10. Serial peripherals</h2>
1507 <div class="sectionbody">
1508 <div class="paragraph">
1509 <p>The CC1111 provides two USART peripherals. AltOS uses one for
1510 asynch serial data, generally to communicate with a GPS
1511 device, and the other for a SPI bus. The UART is configured to
1512 operate in 8-bits, no parity, 1 stop bit framing. The default
1513 configuration has clock settings for 4800, 9600 and 57600 baud
1514 operation. Additional speeds can be added by computing
1515 appropriate clock values.</p>
1516 </div>
1517 <div class="paragraph">
1518 <p>To prevent loss of data, AltOS provides receive and transmit
1519 fifos of 32 characters each.</p>
1520 </div>
1521 <div class="sect2">
1522 <h3 id="_ao_serial_getchar">10.1. ao_serial_getchar</h3>
1523 <div class="literalblock">
1524 <div class="content">
1525 <pre>char
1526 ao_serial_getchar(void);</pre>
1527 </div>
1528 </div>
1529 <div class="paragraph">
1530 <p>Returns the next character from the receive fifo, blocking
1531 until a character is received if the fifo is empty.</p>
1532 </div>
1533 </div>
1534 <div class="sect2">
1535 <h3 id="_ao_serial_putchar">10.2. ao_serial_putchar</h3>
1536 <div class="literalblock">
1537 <div class="content">
1538 <pre>void
1539 ao_serial_putchar(char c);</pre>
1540 </div>
1541 </div>
1542 <div class="paragraph">
1543 <p>Adds a character to the transmit fifo, blocking if the
1544 fifo is full. Starts transmitting characters.</p>
1545 </div>
1546 </div>
1547 <div class="sect2">
1548 <h3 id="_ao_serial_drain">10.3. ao_serial_drain</h3>
1549 <div class="literalblock">
1550 <div class="content">
1551 <pre>void
1552 ao_serial_drain(void);</pre>
1553 </div>
1554 </div>
1555 <div class="paragraph">
1556 <p>Blocks until the transmit fifo is empty. Used internally
1557 when changing serial speeds.</p>
1558 </div>
1559 </div>
1560 <div class="sect2">
1561 <h3 id="_ao_serial_set_speed">10.4. ao_serial_set_speed</h3>
1562 <div class="literalblock">
1563 <div class="content">
1564 <pre>void
1565 ao_serial_set_speed(uint8_t speed);</pre>
1566 </div>
1567 </div>
1568 <div class="paragraph">
1569 <p>Changes the serial baud rate to one of
1570 AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or
1571 AO_SERIAL_SPEED_57600. This first flushes the transmit
1572 fifo using ao_serial_drain.</p>
1573 </div>
1574 </div>
1575 <div class="sect2">
1576 <h3 id="_ao_serial_init">10.5. ao_serial_init</h3>
1577 <div class="literalblock">
1578 <div class="content">
1579 <pre>void
1580 ao_serial_init(void)</pre>
1581 </div>
1582 </div>
1583 <div class="paragraph">
1584 <p>Initializes the serial peripheral. Call this from 'main'
1585 before jumping to ao_start_scheduler. The default speed
1586 setting is AO_SERIAL_SPEED_4800.</p>
1587 </div>
1588 </div>
1589 </div>
1590 </div>
1591 <div class="sect1">
1592 <h2 id="_cc1111cc1120cc1200_radio_peripheral">11. CC1111/CC1120/CC1200 Radio peripheral</h2>
1593 <div class="sectionbody">
1594 <div class="sect2">
1595 <h3 id="_radio_introduction">11.1. Radio Introduction</h3>
1596 <div class="paragraph">
1597 <p>The CC1111, CC1120 and CC1200 radio transceiver sends
1598 and receives digital packets with forward error
1599 correction and detection. The AltOS driver is fairly
1600 specific to the needs of the TeleMetrum and TeleDongle
1601 devices, using it for other tasks may require
1602 customization of the driver itself. There are three
1603 basic modes of operation:</p>
1604 </div>
1605 <div class="olist arabic">
1606 <ol class="arabic">
1607 <li>
1608 <p>Telemetry mode. In this mode, TeleMetrum transmits telemetry
1609 frames at a fixed rate. The frames are of fixed size. This
1610 is strictly a one-way communication from TeleMetrum to
1611 TeleDongle.</p>
1612 </li>
1613 <li>
1614 <p>Packet mode. In this mode, the radio is used to create a
1615 reliable duplex byte stream between TeleDongle and
1616 TeleMetrum. This is an asymmetrical protocol with
1617 TeleMetrum only transmitting in response to a packet sent
1618 from TeleDongle. Thus getting data from TeleMetrum to
1619 TeleDongle requires polling. The polling rate is adaptive,
1620 when no data has been received for a while, the rate slows
1621 down. The packets are checked at both ends and invalid data
1622 are ignored.</p>
1623 </li>
1624 </ol>
1625 </div>
1626 <div class="paragraph">
1627 <p>On the TeleMetrum side, the packet link is hooked into the
1628 stdio mechanism, providing an alternate data path for the
1629 command processor. It is enabled when the unit boots up in
1630 'idle' mode.</p>
1631 </div>
1632 <div class="paragraph">
1633 <p>On the TeleDongle side, the packet link is enabled with a
1634 command; data from the stdio package is forwarded over the
1635 packet link providing a connection from the USB command
1636 stream to the remote TeleMetrum device.</p>
1637 </div>
1638 <div class="olist arabic">
1639 <ol class="arabic">
1640 <li>
1641 <p>Radio Direction Finding mode. In this mode, TeleMetrum
1642 constructs a special packet that sounds like an audio tone
1643 when received by a conventional narrow-band FM
1644 receiver. This is designed to provide a beacon to track the
1645 device when other location mechanisms fail.</p>
1646 </li>
1647 </ol>
1648 </div>
1649 </div>
1650 <div class="sect2">
1651 <h3 id="_ao_radio_set_telemetry">11.2. ao_radio_set_telemetry</h3>
1652 <div class="literalblock">
1653 <div class="content">
1654 <pre>void
1655 ao_radio_set_telemetry(void);</pre>
1656 </div>
1657 </div>
1658 <div class="paragraph">
1659 <p>Configures the radio to send or receive telemetry
1660 packets. This includes packet length, modulation scheme and
1661 other RF parameters. It does not include the base frequency
1662 or channel though. Those are set at the time of transmission
1663 or reception, in case the values are changed by the user.</p>
1664 </div>
1665 </div>
1666 <div class="sect2">
1667 <h3 id="_ao_radio_set_packet">11.3. ao_radio_set_packet</h3>
1668 <div class="literalblock">
1669 <div class="content">
1670 <pre>void
1671 ao_radio_set_packet(void);</pre>
1672 </div>
1673 </div>
1674 <div class="paragraph">
1675 <p>Configures the radio to send or receive packet data.  This
1676 includes packet length, modulation scheme and other RF
1677 parameters. It does not include the base frequency or
1678 channel though. Those are set at the time of transmission or
1679 reception, in case the values are changed by the user.</p>
1680 </div>
1681 </div>
1682 <div class="sect2">
1683 <h3 id="_ao_radio_set_rdf">11.4. ao_radio_set_rdf</h3>
1684 <div class="literalblock">
1685 <div class="content">
1686 <pre>void
1687 ao_radio_set_rdf(void);</pre>
1688 </div>
1689 </div>
1690 <div class="paragraph">
1691 <p>Configures the radio to send RDF 'packets'. An RDF 'packet'
1692 is a sequence of hex 0x55 bytes sent at a base bit rate of
1693 2kbps using a 5kHz deviation. All of the error correction
1694 and data whitening logic is turned off so that the resulting
1695 modulation is received as a 1kHz tone by a conventional 70cm
1696 FM audio receiver.</p>
1697 </div>
1698 </div>
1699 <div class="sect2">
1700 <h3 id="_ao_radio_idle">11.5. ao_radio_idle</h3>
1701 <div class="literalblock">
1702 <div class="content">
1703 <pre>void
1704 ao_radio_idle(void);</pre>
1705 </div>
1706 </div>
1707 <div class="paragraph">
1708 <p>Sets the radio device to idle mode, waiting until it reaches
1709 that state. This will terminate any in-progress transmit or
1710 receive operation.</p>
1711 </div>
1712 </div>
1713 <div class="sect2">
1714 <h3 id="_ao_radio_get">11.6. ao_radio_get</h3>
1715 <div class="literalblock">
1716 <div class="content">
1717 <pre>void
1718 ao_radio_get(void);</pre>
1719 </div>
1720 </div>
1721 <div class="paragraph">
1722 <p>Acquires the radio mutex and then configures the radio
1723 frequency using the global radio calibration and channel
1724 values.</p>
1725 </div>
1726 </div>
1727 <div class="sect2">
1728 <h3 id="_ao_radio_put">11.7. ao_radio_put</h3>
1729 <div class="literalblock">
1730 <div class="content">
1731 <pre>void
1732 ao_radio_put(void);</pre>
1733 </div>
1734 </div>
1735 <div class="paragraph">
1736 <p>Releases the radio mutex.</p>
1737 </div>
1738 </div>
1739 <div class="sect2">
1740 <h3 id="_ao_radio_abort">11.8. ao_radio_abort</h3>
1741 <div class="literalblock">
1742 <div class="content">
1743 <pre>void
1744 ao_radio_abort(void);</pre>
1745 </div>
1746 </div>
1747 <div class="paragraph">
1748 <p>Aborts any transmission or reception process by aborting the
1749 associated DMA object and calling ao_radio_idle to terminate
1750 the radio operation.</p>
1751 </div>
1752 </div>
1753 <div class="sect2">
1754 <h3 id="_radio_telemetry">11.9. Radio Telemetry</h3>
1755 <div class="paragraph">
1756 <p>In telemetry mode, you can send or receive a telemetry
1757 packet. The data from receiving a packet also includes the RSSI
1758 and status values supplied by the receiver. These are added
1759 after the telemetry data.</p>
1760 </div>
1761 <div class="sect3">
1762 <h4 id="_ao_radio_send">11.9.1. ao_radio_send</h4>
1763 <div class="literalblock">
1764 <div class="content">
1765 <pre>void
1766 ao_radio_send(__xdata struct ao_telemetry *telemetry);</pre>
1767 </div>
1768 </div>
1769 <div class="paragraph">
1770 <p>This sends the specific telemetry packet, waiting for the
1771 transmission to complete. The radio must have been set to
1772 telemetry mode. This function calls ao_radio_get() before
1773 sending, and ao_radio_put() afterwards, to correctly
1774 serialize access to the radio device.</p>
1775 </div>
1776 </div>
1777 <div class="sect3">
1778 <h4 id="_ao_radio_recv">11.9.2. ao_radio_recv</h4>
1779 <div class="literalblock">
1780 <div class="content">
1781 <pre>void
1782 ao_radio_recv(__xdata struct ao_radio_recv *radio);</pre>
1783 </div>
1784 </div>
1785 <div class="paragraph">
1786 <p>This blocks waiting for a telemetry packet to be received.
1787 The radio must have been set to telemetry mode. This
1788 function calls ao_radio_get() before receiving, and
1789 ao_radio_put() afterwards, to correctly serialize access
1790 to the radio device. This returns non-zero if a packet was
1791 received, or zero if the operation was aborted (from some
1792 other task calling ao_radio_abort()).</p>
1793 </div>
1794 </div>
1795 </div>
1796 <div class="sect2">
1797 <h3 id="_radio_direction_finding">11.10. Radio Direction Finding</h3>
1798 <div class="paragraph">
1799 <p>In radio direction finding mode, there&#8217;s just one function to
1800 use</p>
1801 </div>
1802 <div class="sect3">
1803 <h4 id="_ao_radio_rdf">11.10.1. ao_radio_rdf</h4>
1804 <div class="literalblock">
1805 <div class="content">
1806 <pre>void
1807 ao_radio_rdf(int ms);</pre>
1808 </div>
1809 </div>
1810 <div class="paragraph">
1811 <p>This sends an RDF packet lasting for the specified amount
1812 of time. The maximum length is 1020 ms.</p>
1813 </div>
1814 </div>
1815 </div>
1816 <div class="sect2">
1817 <h3 id="_radio_packet_mode">11.11. Radio Packet Mode</h3>
1818 <div class="paragraph">
1819 <p>Packet mode is asymmetrical and is configured at compile time
1820 for either master or slave mode (but not both). The basic I/O
1821 functions look the same at both ends, but the internals are
1822 different, along with the initialization steps.</p>
1823 </div>
1824 <div class="sect3">
1825 <h4 id="_ao_packet_putchar">11.11.1. ao_packet_putchar</h4>
1826 <div class="literalblock">
1827 <div class="content">
1828 <pre>void
1829 ao_packet_putchar(char c);</pre>
1830 </div>
1831 </div>
1832 <div class="paragraph">
1833 <p>If the output queue is full, this first blocks waiting for
1834 that data to be delivered. Then, queues a character for
1835 packet transmission. On the master side, this will
1836 transmit a packet if the output buffer is full. On the
1837 slave side, any pending data will be sent the next time
1838 the master polls for data.</p>
1839 </div>
1840 </div>
1841 <div class="sect3">
1842 <h4 id="_ao_packet_pollchar">11.11.2. ao_packet_pollchar</h4>
1843 <div class="literalblock">
1844 <div class="content">
1845 <pre>char
1846 ao_packet_pollchar(void);</pre>
1847 </div>
1848 </div>
1849 <div class="paragraph">
1850 <p>This returns a pending input character if available,
1851 otherwise returns AO_READ_AGAIN. On the master side, if
1852 this empties the buffer, it triggers a poll for more data.</p>
1853 </div>
1854 </div>
1855 <div class="sect3">
1856 <h4 id="_ao_packet_slave_start">11.11.3. ao_packet_slave_start</h4>
1857 <div class="literalblock">
1858 <div class="content">
1859 <pre>void
1860 ao_packet_slave_start(void);</pre>
1861 </div>
1862 </div>
1863 <div class="paragraph">
1864 <p>This is available only on the slave side and starts a task
1865 to listen for packet data.</p>
1866 </div>
1867 </div>
1868 <div class="sect3">
1869 <h4 id="_ao_packet_slave_stop">11.11.4. ao_packet_slave_stop</h4>
1870 <div class="literalblock">
1871 <div class="content">
1872 <pre>void
1873 ao_packet_slave_stop(void);</pre>
1874 </div>
1875 </div>
1876 <div class="paragraph">
1877 <p>Disables the packet slave task, stopping the radio receiver.</p>
1878 </div>
1879 </div>
1880 <div class="sect3">
1881 <h4 id="_ao_packet_slave_init">11.11.5. ao_packet_slave_init</h4>
1882 <div class="literalblock">
1883 <div class="content">
1884 <pre>void
1885 ao_packet_slave_init(void);</pre>
1886 </div>
1887 </div>
1888 <div class="paragraph">
1889 <p>Adds the packet stdio functions to the stdio package so
1890 that when packet slave mode is enabled, characters will
1891 get send and received through the stdio functions.</p>
1892 </div>
1893 </div>
1894 <div class="sect3">
1895 <h4 id="_ao_packet_master_init">11.11.6. ao_packet_master_init</h4>
1896 <div class="literalblock">
1897 <div class="content">
1898 <pre>void
1899 ao_packet_master_init(void);</pre>
1900 </div>
1901 </div>
1902 <div class="paragraph">
1903 <p>Adds the 'p' packet forward command to start packet mode.</p>
1904 </div>
1905 </div>
1906 </div>
1907 </div>
1908 </div>
1909 </div>
1910 <div id="footer">
1911 <div id="footer-text">
1912 Last updated 2020-10-22 16:37:05 -0600
1913 </div>
1914 </div>
1915 </body>
1916 </html>