1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd">
7 <subtitle>Altos Metrum Operating System</subtitle>
10 <firstname>Keith</firstname>
11 <surname>Packard</surname>
15 <holder>Keith Packard</holder>
19 This document is released under the terms of the
20 <ulink url="http://creativecommons.org/licenses/by-sa/3.0/">
21 Creative Commons ShareAlike 3.0
28 <revnumber>1.1</revnumber>
29 <date>05 November 2012</date>
30 <revremark>Portable version</revremark>
33 <revnumber>0.1</revnumber>
34 <date>22 November 2010</date>
35 <revremark>Initial content</revremark>
40 <title>Overview</title>
42 AltOS is a operating system built for a variety of
43 microcontrollers used in Altus Metrum devices. It has a simple
44 porting layer for each CPU while providing a convenient
45 operating enviroment for the developer. AltOS currently
46 supports three different CPUs:
50 STM32L series from ST Microelectronics. This ARM Cortex-M3
51 based microcontroller offers low power consumption and a
52 wide variety of built-in peripherals. Altus Metrum uses
53 this in the TeleMega, MegaDongle and TeleLCO projects.
58 CC1111 from Texas Instruments. This device includes a
59 fabulous 10mW digital RF transceiver along with an
60 8051-compatible processor core and a range of
61 peripherals. This is used in the TeleMetrum, TeleMini,
62 TeleDongle and TeleFire projects which share the need for
63 a small microcontroller and an RF interface.
68 ATmega32U4 from Atmel. This 8-bit AVR microcontroller is
69 one of the many used to create Arduino boards. The 32U4
70 includes a USB interface, making it easy to connect to
71 other computers. Altus Metrum used this in prototypes of
72 the TeleScience and TelePyro boards; those have been
73 switched to the STM32L which is more capable and cheaper.
77 Among the features of AltOS are:
80 <para>Multi-tasking. While microcontrollers often don't
81 provide separate address spaces, it's often easier to write
82 code that operates in separate threads instead of tying
83 everything into one giant event loop.
87 <para>Non-preemptive. This increases latency for thread
88 switching but reduces the number of places where context
89 switching can occur. It also simplifies the operating system
90 design somewhat. Nothing in the target system (rocket flight
91 control) has tight timing requirements, and so this seems like
92 a reasonable compromise.
96 <para>Sleep/wakeup scheduling. Taken directly from ancient
97 Unix designs, these two provide the fundemental scheduling
98 primitive within AltOS.
102 <para>Mutexes. As a locking primitive, mutexes are easier to
103 use than semaphores, at least in my experience.
107 <para>Timers. Tasks can set an alarm which will abort any
108 pending sleep, allowing operations to time-out instead of
115 The device drivers and other subsystems in AltOS are
116 conventionally enabled by invoking their _init() function from
117 the 'main' function before that calls
118 ao_start_scheduler(). These functions initialize the pin
119 assignments, add various commands to the command processor and
120 may add tasks to the scheduler to handle the device. A typical
121 main program, thus, looks like:
128 /* Turn on the LED until the system is stable */
129 ao_led_init(LEDS_AVAILABLE);
130 ao_led_on(AO_LED_RED);
134 ao_monitor_init(AO_LED_GREEN, TRUE);
135 ao_rssi_init(AO_LED_RED);
137 ao_packet_slave_init();
138 ao_packet_master_init();
143 ao_start_scheduler();
146 As you can see, a long sequence of subsystems are initialized
147 and then the scheduler is started.
151 <title>AltOS Porting Layer</title>
153 AltOS provides a CPU-independent interface to various common
154 microcontroller subsystems, including GPIO pins, interrupts,
155 SPI, I2C, USB and asynchronous serial interfaces. By making
156 these CPU-independent, device drivers, generic OS and
157 application code can all be written that work on any supported
158 CPU. Many of the architecture abstraction interfaces are
159 prefixed with ao_arch.
162 <title>Low-level CPU operations</title>
164 These primitive operations provide the abstraction needed to
165 run the multi-tasking framework while providing reliable
169 <title>ao_arch_block_interrupts/ao_arch_release_interrupts</title>
172 ao_arch_block_interrupts(void);
175 ao_arch_release_interrupts(void);
178 These disable/enable interrupt delivery, they may not
179 discard any interrupts. Use these for sections of code that
180 must be atomic with respect to any code run from an
185 <title>ao_arch_save_regs, ao_arch_save_stack,
186 ao_arch_restore_stack</title>
189 ao_arch_save_regs(void);
192 ao_arch_save_stack(void);
195 ao_arch_restore_stack(void);
198 These provide all of the support needed to switch between
199 tasks.. ao_arch_save_regs must save all CPU registers to the
200 current stack, including the interrupt enable
201 state. ao_arch_save_stack records the current stack location
202 in the current ao_task structure. ao_arch_restore_stack
203 switches back to the saved stack, restores all registers and
204 branches to the saved return address.
208 <title>ao_arch_wait_interupt</title>
210 #define ao_arch_wait_interrupt()
213 This stops the CPU, leaving clocks and interrupts
214 enabled. When an interrupt is received, this must wake up
215 and handle the interrupt. ao_arch_wait_interrupt is entered
216 with interrupts disabled to ensure that there is no gap
217 between determining that no task wants to run and idling the
218 CPU. It must sleep the CPU, process interrupts and then
219 disable interrupts again. If the CPU doesn't have any
220 reduced power mode, this must at the least allow pending
221 interrupts to be processed.
226 <title>GPIO operations</title>
228 These functions provide an abstract interface to configure and
229 manipulate GPIO pins.
232 <title>GPIO setup</title>
234 These macros may be invoked at system initialization time to
235 configure pins as needed for system operation. One tricky
236 aspect is that some chips provide direct access to specific
237 GPIO pins while others only provide access to a whole
238 register full of pins. To support this, the GPIO macros
239 provide both port+bit and pin arguments. Simply define the
240 arguments needed for the target platform and leave the
244 <title>ao_enable_output</title>
246 #define ao_enable_output(port, bit, pin, value)
249 Set the specified port+bit (also called 'pin') for output,
250 initializing to the specified value. The macro must avoid
251 driving the pin with the opposite value if at all
256 <title>ao_enable_input</title>
258 #define ao_enable_input(port, bit, mode)
261 Sets the specified port/bit to be an input pin. 'mode' is
262 a combination of one or more of the following. Note that
263 some platforms may not support the desired mode. In that
264 case, the value will not be defined so that the program
265 will fail to compile.
268 AO_EXTI_MODE_PULL_UP. Apply a pull-up to the pin; a
269 disconnected pin will read as 1.
272 AO_EXTI_MODE_PULL_DOWN. Apply a pull-down to the pin;
273 a disconnected pin will read as 0.
276 0. Don't apply either a pull-up or pull-down. A
277 disconnected pin will read an undetermined value.
284 <title>Reading and writing GPIO pins</title>
286 These macros read and write individual GPIO pins.
289 <title>ao_gpio_set</title>
291 #define ao_gpio_set(port, bit, pin, value)
294 Sets the specified port/bit or pin to the indicated value
298 <title>ao_gpio_get</title>
300 #define ao_gpio_get(port, bit, pin)
303 Returns either 1 or 0 depending on whether the input to
304 the pin is high or low.
311 <title>Programming the 8051 with SDCC</title>
313 The 8051 is a primitive 8-bit processor, designed in the mists
314 of time in as few transistors as possible. The architecture is
315 highly irregular and includes several separate memory
316 spaces. Furthermore, accessing stack variables is slow, and the
317 stack itself is of limited size. While SDCC papers over the
318 instruction set, it is not completely able to hide the memory
319 architecture from the application designer.
322 When built on other architectures, the various SDCC-specific
323 symbols are #defined as empty strings so they don't affect the compiler.
326 <title>8051 memory spaces</title>
328 The __data/__xdata/__code memory spaces below were completely
329 separate in the original 8051 design. In the cc1111, this
330 isn't true—they all live in a single unified 64kB address
331 space, and so it's possible to convert any address into a
332 unique 16-bit address. SDCC doesn't know this, and so a
333 'global' address to SDCC consumes 3 bytes of memory, 1 byte as
334 a tag indicating the memory space and 2 bytes of offset within
335 that space. AltOS avoids these 3-byte addresses as much as
336 possible; using them involves a function call per byte
337 access. The result is that nearly every variable declaration
338 is decorated with a memory space identifier which clutters the
339 code but makes the resulting code far smaller and more
343 <title>__data</title>
345 The 8051 can directly address these 128 bytes of
346 memory. This makes them precious so they should be
347 reserved for frequently addressed values. Oh, just to
348 confuse things further, the 8 general registers in the
349 CPU are actually stored in this memory space. There are
350 magic instructions to 'bank switch' among 4 banks of
351 these registers located at 0x00 - 0x1F. AltOS uses only
352 the first bank at 0x00 - 0x07, leaving the other 24
353 bytes available for other data.
357 <title>__idata</title>
359 There are an additional 128 bytes of internal memory
360 that share the same address space as __data but which
361 cannot be directly addressed. The stack normally
362 occupies this space and so AltOS doesn't place any
367 <title>__xdata</title>
369 This is additional general memory accessed through a
370 single 16-bit address register. The CC1111F32 has 32kB
371 of memory available here. Most program data should live
372 in this memory space.
376 <title>__pdata</title>
378 This is an alias for the first 256 bytes of __xdata
379 memory, but uses a shorter addressing mode with
380 single global 8-bit value for the high 8 bits of the
381 address and any of several 8-bit registers for the low 8
382 bits. AltOS uses a few bits of this memory, it should
387 <title>__code</title>
389 All executable code must live in this address space, but
390 you can stick read-only data here too. It is addressed
391 using the 16-bit address register and special 'code'
392 access opcodes. Anything read-only should live in this space.
398 The 8051 has 128 bits of bit-addressible memory that
399 lives in the __data segment from 0x20 through
400 0x2f. Special instructions access these bits
401 in a single atomic operation. This isn't so much a
402 separate address space as a special addressing mode for
403 a few bytes in the __data segment.
407 <title>__sfr, __sfr16, __sfr32, __sbit</title>
409 Access to physical registers in the device use this mode
410 which declares the variable name, it's type and the
411 address it lives at. No memory is allocated for these
417 <title>Function calls on the 8051</title>
419 Because stack addressing is expensive, and stack space
420 limited, the default function call declaration in SDCC
421 allocates all parameters and local variables in static global
422 memory. Just like fortran. This makes these functions
423 non-reentrant, and also consume space for parameters and
424 locals even when they are not running. The benefit is smaller
425 code and faster execution.
428 <title>__reentrant functions</title>
430 All functions which are re-entrant, either due to recursion
431 or due to a potential context switch while executing, should
432 be marked as __reentrant so that their parameters and local
433 variables get allocated on the stack. This ensures that
434 these values are not overwritten by another invocation of
438 Functions which use significant amounts of space for
439 arguments and/or local variables and which are not often
440 invoked can also be marked as __reentrant. The resulting
441 code will be larger, but the savings in memory are
442 frequently worthwhile.
446 <title>Non __reentrant functions</title>
448 All parameters and locals in non-reentrant functions can
449 have data space decoration so that they are allocated in
450 __xdata, __pdata or __data space as desired. This can avoid
451 consuming __data space for infrequently used variables in
452 frequently used functions.
455 All library functions called by SDCC, including functions
456 for multiplying and dividing large data types, are
457 non-reentrant. Because of this, interrupt handlers must not
458 invoke any library functions, including the multiply and
463 <title>__interrupt functions</title>
465 Interrupt functions are declared with with an __interrupt
466 decoration that includes the interrupt number. SDCC saves
467 and restores all of the registers in these functions and
468 uses the 'reti' instruction at the end so that they operate
469 as stand-alone interrupt handlers. Interrupt functions may
470 call the ao_wakeup function to wake AltOS tasks.
474 <title>__critical functions and statements</title>
476 SDCC has built-in support for suspending interrupts during
477 critical code. Functions marked as __critical will have
478 interrupts suspended for the whole period of
479 execution. Individual statements may also be marked as
480 __critical which blocks interrupts during the execution of
481 that statement. Keeping critical sections as short as
482 possible is key to ensuring that interrupts are handled as
483 quickly as possible. AltOS doesn't use this form in shared
484 code as other compilers wouldn't know what to do. Use
485 ao_arch_block_interrupts and ao_arch_release_interrupts instead.
491 <title>Task functions</title>
493 This chapter documents how to create, destroy and schedule AltOS tasks.
496 <title>ao_add_task</title>
499 ao_add_task(__xdata struct ao_task * task,
504 This initializes the statically allocated task structure,
505 assigns a name to it (not used for anything but the task
506 display), and the start address. It does not switch to the
507 new task. 'start' must not ever return; there is no place
512 <title>ao_exit</title>
518 This terminates the current task.
522 <title>ao_sleep</title>
525 ao_sleep(__xdata void *wchan)
528 This suspends the current task until 'wchan' is signaled
529 by ao_wakeup, or until the timeout, set by ao_alarm,
530 fires. If 'wchan' is signaled, ao_sleep returns 0, otherwise
531 it returns 1. This is the only way to switch to another task.
534 Because ao_wakeup wakes every task waiting on a particular
535 location, ao_sleep should be used in a loop that first checks
536 the desired condition, blocks in ao_sleep and then rechecks
537 until the condition is satisfied. If the location may be
538 signaled from an interrupt handler, the code will need to
539 block interrupts around the block of code. Here's a complete
542 ao_arch_block_interrupts();
543 while (!ao_radio_done)
544 ao_sleep(&ao_radio_done);
545 ao_arch_release_interrupts();
550 <title>ao_wakeup</title>
553 ao_wakeup(__xdata void *wchan)
556 Wake all tasks blocked on 'wchan'. This makes them
557 available to be run again, but does not actually switch
558 to another task. Here's an example of using this:
560 if (RFIF & RFIF_IM_DONE) {
562 ao_wakeup(&ao_radio_done);
563 RFIF &= ~RFIF_IM_DONE;
566 Note that this need not block interrupts as the ao_sleep block
567 can only be run from normal mode, and so this sequence can
568 never be interrupted with execution of the other sequence.
572 <title>ao_alarm</title>
575 ao_alarm(uint16_t delay);
578 ao_clear_alarm(void);
581 Schedules an alarm to fire in at least 'delay' ticks. If the
582 task is asleep when the alarm fires, it will wakeup and
583 ao_sleep will return 1. ao_clear_alarm resets any pending
584 alarm so that it doesn't fire at some arbitrary point in the
587 ao_alarm(ao_packet_master_delay);
588 ao_arch_block_interrupts();
589 while (!ao_radio_dma_done)
590 if (ao_sleep(&ao_radio_dma_done) != 0)
592 ao_arch_release_interrupts();
595 In this example, a timeout is set before waiting for
596 incoming radio data. If no data is received before the
597 timeout fires, ao_sleep will return 1 and then this code
598 will abort the radio receive operation.
602 <title>ao_start_scheduler</title>
605 ao_start_scheduler(void);
608 This is called from 'main' when the system is all
609 initialized and ready to run. It will not return.
613 <title>ao_clock_init</title>
619 This initializes the main CPU clock and switches to it.
624 <title>Timer Functions</title>
626 AltOS sets up one of the CPU timers to run at 100Hz and
627 exposes this tick as the fundemental unit of time. At each
628 interrupt, AltOS increments the counter, and schedules any tasks
629 waiting for that time to pass, then fires off the sensors to
630 collect current data readings. Doing this from the ISR ensures
631 that the values are sampled at a regular rate, independent
632 of any scheduling jitter.
635 <title>ao_time</title>
641 Returns the current system tick count. Note that this is
642 only a 16 bit value, and so it wraps every 655.36 seconds.
646 <title>ao_delay</title>
649 ao_delay(uint16_t ticks);
652 Suspend the current task for at least 'ticks' clock units.
656 <title>ao_timer_set_adc_interval</title>
659 ao_timer_set_adc_interval(uint8_t interval);
662 This sets the number of ticks between ADC samples. If set
663 to 0, no ADC samples are generated. AltOS uses this to
664 slow down the ADC sampling rate to save power.
668 <title>ao_timer_init</title>
674 This turns on the 100Hz tick. It is required for any of the
675 time-based functions to work. It should be called by 'main'
676 before ao_start_scheduler.
681 <title>AltOS Mutexes</title>
683 AltOS provides mutexes as a basic synchronization primitive. Each
684 mutexes is simply a byte of memory which holds 0 when the mutex
685 is free or the task id of the owning task when the mutex is
686 owned. Mutex calls are checked—attempting to acquire a mutex
687 already held by the current task or releasing a mutex not held
688 by the current task will both cause a panic.
691 <title>ao_mutex_get</title>
694 ao_mutex_get(__xdata uint8_t *mutex);
697 Acquires the specified mutex, blocking if the mutex is
698 owned by another task.
702 <title>ao_mutex_put</title>
705 ao_mutex_put(__xdata uint8_t *mutex);
708 Releases the specified mutex, waking up all tasks waiting
714 <title>DMA engine</title>
716 The CC1111 and STM32L both contain a useful bit of extra
717 hardware in the form of a number of programmable DMA
718 engines. They can be configured to copy data in memory, or
719 between memory and devices (or even between two devices). AltOS
720 exposes a general interface to this hardware and uses it to
721 handle both internal and external devices.
724 Because the CC1111 and STM32L DMA engines are different, the
725 interface to them is also different. As the DMA engines are
726 currently used to implement platform-specific drivers, this
730 Code using a DMA engine should allocate one at startup
731 time. There is no provision to free them, and if you run out,
732 AltOS will simply panic.
735 During operation, the DMA engine is initialized with the
736 transfer parameters. Then it is started, at which point it
737 awaits a suitable event to start copying data. When copying data
738 from hardware to memory, that trigger event is supplied by the
739 hardware device. When copying data from memory to hardware, the
740 transfer is usually initiated by software.
743 <title>CC1111 DMA Engine</title>
745 <title>ao_dma_alloc</title>
748 ao_dma_alloc(__xdata uint8_t *done)
751 Allocate a DMA engine, returning the identifier. 'done' is
752 cleared when the DMA is started, and then receives the
753 AO_DMA_DONE bit on a successful transfer or the
754 AO_DMA_ABORTED bit if ao_dma_abort was called. Note that it
755 is possible to get both bits if the transfer was aborted
756 after it had finished.
760 <title>ao_dma_set_transfer</title>
763 ao_dma_set_transfer(uint8_t id,
764 void __xdata *srcaddr,
765 void __xdata *dstaddr,
771 Initializes the specified dma engine to copy data
772 from 'srcaddr' to 'dstaddr' for 'count' units. cfg0 and
773 cfg1 are values directly out of the CC1111 documentation
774 and tell the DMA engine what the transfer unit size,
775 direction and step are.
779 <title>ao_dma_start</title>
782 ao_dma_start(uint8_t id);
785 Arm the specified DMA engine and await a signal from
786 either hardware or software to start transferring data.
790 <title>ao_dma_trigger</title>
793 ao_dma_trigger(uint8_t id)
796 Trigger the specified DMA engine to start copying data.
800 <title>ao_dma_abort</title>
803 ao_dma_abort(uint8_t id)
806 Terminate any in-progress DMA transation, marking its
807 'done' variable with the AO_DMA_ABORTED bit.
812 <title>STM32L DMA Engine</title>
814 <title>ao_dma_alloc</title>
816 uint8_t ao_dma_done[];
819 ao_dma_alloc(uint8_t index);
822 Reserve a DMA engine for exclusive use by one
827 <title>ao_dma_set_transfer</title>
830 ao_dma_set_transfer(uint8_t id,
837 Initializes the specified dma engine to copy data between
838 'peripheral' and 'memory' for 'count' units. 'ccr' is a
839 value directly out of the STM32L documentation and tells the
840 DMA engine what the transfer unit size, direction and step
845 <title>ao_dma_set_isr</title>
848 ao_dma_set_isr(uint8_t index, void (*isr)(int))
851 This sets a function to be called when the DMA transfer
852 completes in lieu of setting the ao_dma_done bits. Use this
853 when some work needs to be done when the DMA finishes that
854 cannot wait until user space resumes.
858 <title>ao_dma_start</title>
861 ao_dma_start(uint8_t id);
864 Arm the specified DMA engine and await a signal from either
865 hardware or software to start transferring data.
866 'ao_dma_done[index]' is cleared when the DMA is started, and
867 then receives the AO_DMA_DONE bit on a successful transfer
868 or the AO_DMA_ABORTED bit if ao_dma_abort was called. Note
869 that it is possible to get both bits if the transfer was
870 aborted after it had finished.
874 <title>ao_dma_done_transfer</title>
877 ao_dma_done_transfer(uint8_t id);
880 Signals that a specific DMA engine is done being used. This
881 allows multiple drivers to use the same DMA engine safely.
885 <title>ao_dma_abort</title>
888 ao_dma_abort(uint8_t id)
891 Terminate any in-progress DMA transation, marking its
892 'done' variable with the AO_DMA_ABORTED bit.
898 <title>Stdio interface</title>
900 AltOS offers a stdio interface over USB, serial and the RF
901 packet link. This provides for control of the device localy or
902 remotely. This is hooked up to the stdio functions by providing
903 the standard putchar/getchar/flush functions. These
904 automatically multiplex the available communication channels;
905 output is always delivered to the channel which provided the
909 <title>putchar</title>
915 Delivers a single character to the current console
920 <title>getchar</title>
926 Reads a single character from any of the available
927 console devices. The current console device is set to
928 that which delivered this character. This blocks until
929 a character is available.
939 Flushes the current console device output buffer. Any
940 pending characters will be delivered to the target device.
944 <title>ao_add_stdio</title>
947 ao_add_stdio(char (*pollchar)(void),
948 void (*putchar)(char),
952 This adds another console device to the available
956 'pollchar' returns either an available character or
957 AO_READ_AGAIN if none is available. Significantly, it does
958 not block. The device driver must set 'ao_stdin_ready' to
959 1 and call ao_wakeup(&ao_stdin_ready) when it receives
960 input to tell getchar that more data is available, at
961 which point 'pollchar' will be called again.
964 'putchar' queues a character for output, flushing if the output buffer is
965 full. It may block in this case.
968 'flush' forces the output buffer to be flushed. It may
969 block until the buffer is delivered, but it is not
975 <title>Command line interface</title>
977 AltOS includes a simple command line parser which is hooked up
978 to the stdio interfaces permitting remote control of the device
979 over USB, serial or the RF link as desired. Each command uses a
980 single character to invoke it, the remaining characters on the
981 line are available as parameters to the command.
984 <title>ao_cmd_register</title>
987 ao_cmd_register(__code struct ao_cmds *cmds)
990 This registers a set of commands with the command
991 parser. There is a fixed limit on the number of command
992 sets, the system will panic if too many are registered.
993 Each command is defined by a struct ao_cmds entry:
1001 'cmd' is the character naming the command. 'func' is the
1002 function to invoke and 'help' is a string displayed by the
1003 '?' command. Syntax errors found while executing 'func'
1004 should be indicated by modifying the global ao_cmd_status
1005 variable with one of the following values:
1008 <title>ao_cmd_success</title>
1011 The command was parsed successfully. There is no
1012 need to assign this value, it is the default.
1017 <title>ao_cmd_lex_error</title>
1020 A token in the line was invalid, such as a number
1021 containing invalid characters. The low-level
1022 lexing functions already assign this value as needed.
1027 <title>ao_syntax_error</title>
1030 The command line is invalid for some reason other
1031 than invalid tokens.
1039 <title>ao_cmd_lex</title>
1045 This gets the next character out of the command line
1046 buffer and sticks it into ao_cmd_lex_c. At the end of the
1047 line, ao_cmd_lex_c will get a newline ('\n') character.
1051 <title>ao_cmd_put16</title>
1054 ao_cmd_put16(uint16_t v);
1057 Writes 'v' as four hexadecimal characters.
1061 <title>ao_cmd_put8</title>
1064 ao_cmd_put8(uint8_t v);
1067 Writes 'v' as two hexadecimal characters.
1071 <title>ao_cmd_white</title>
1077 This skips whitespace by calling ao_cmd_lex while
1078 ao_cmd_lex_c is either a space or tab. It does not skip
1079 any characters if ao_cmd_lex_c already non-white.
1083 <title>ao_cmd_hex</title>
1089 This reads a 16-bit hexadecimal value from the command
1090 line with optional leading whitespace. The resulting value
1091 is stored in ao_cmd_lex_i;
1095 <title>ao_cmd_decimal</title>
1098 ao_cmd_decimal(void)
1101 This reads a 32-bit decimal value from the command
1102 line with optional leading whitespace. The resulting value
1103 is stored in ao_cmd_lex_u32 and the low 16 bits are stored
1108 <title>ao_match_word</title>
1111 ao_match_word(__code char *word)
1114 This checks to make sure that 'word' occurs on the command
1115 line. It does not skip leading white space. If 'word' is
1116 found, then 1 is returned. Otherwise, ao_cmd_status is set to
1117 ao_cmd_syntax_error and 0 is returned.
1121 <title>ao_cmd_init</title>
1127 Initializes the command system, setting up the built-in
1128 commands and adding a task to run the command processing
1129 loop. It should be called by 'main' before ao_start_scheduler.
1134 <title>USB target device</title>
1136 AltOS contains a full-speed USB target device driver. It can be
1137 programmed to offer any kind of USB target, but to simplify
1138 interactions with a variety of operating systems, AltOS provides
1139 only a single target device profile, that of a USB modem which
1140 has native drivers for Linux, Windows and Mac OS X. It would be
1141 easy to change the code to provide an alternate target device if
1145 To the rest of the system, the USB device looks like a simple
1146 two-way byte stream. It can be hooked into the command line
1147 interface if desired, offering control of the device over the
1148 USB link. Alternatively, the functions can be accessed directly
1149 to provide for USB-specific I/O.
1152 <title>ao_usb_flush</title>
1158 Flushes any pending USB output. This queues an 'IN' packet
1159 to be delivered to the USB host if there is pending data,
1160 or if the last IN packet was full to indicate to the host
1161 that there isn't any more pending data available.
1165 <title>ao_usb_putchar</title>
1168 ao_usb_putchar(char c);
1171 If there is a pending 'IN' packet awaiting delivery to the
1172 host, this blocks until that has been fetched. Then, this
1173 adds a byte to the pending IN packet for delivery to the
1174 USB host. If the USB packet is full, this queues the 'IN'
1175 packet for delivery.
1179 <title>ao_usb_pollchar</title>
1182 ao_usb_pollchar(void);
1185 If there are no characters remaining in the last 'OUT'
1186 packet received, this returns AO_READ_AGAIN. Otherwise, it
1187 returns the next character, reporting to the host that it
1188 is ready for more data when the last character is gone.
1192 <title>ao_usb_getchar</title>
1195 ao_usb_getchar(void);
1198 This uses ao_pollchar to receive the next character,
1199 blocking while ao_pollchar returns AO_READ_AGAIN.
1203 <title>ao_usb_disable</title>
1206 ao_usb_disable(void);
1209 This turns off the USB controller. It will no longer
1210 respond to host requests, nor return characters. Calling
1211 any of the i/o routines while the USB device is disabled
1212 is undefined, and likely to break things. Disabling the
1213 USB device when not needed saves power.
1216 Note that neither TeleDongle nor TeleMetrum are able to
1217 signal to the USB host that they have disconnected, so
1218 after disabling the USB device, it's likely that the cable
1219 will need to be disconnected and reconnected before it
1224 <title>ao_usb_enable</title>
1227 ao_usb_enable(void);
1230 This turns the USB controller on again after it has been
1231 disabled. See the note above about needing to physically
1232 remove and re-insert the cable to get the host to
1233 re-initialize the USB link.
1237 <title>ao_usb_init</title>
1243 This turns the USB controller on, adds a task to handle
1244 the control end point and adds the usb I/O functions to
1245 the stdio system. Call this from main before
1251 <title>Serial peripherals</title>
1253 The CC1111 provides two USART peripherals. AltOS uses one for
1254 asynch serial data, generally to communicate with a GPS device,
1255 and the other for a SPI bus. The UART is configured to operate
1256 in 8-bits, no parity, 1 stop bit framing. The default
1257 configuration has clock settings for 4800, 9600 and 57600 baud
1258 operation. Additional speeds can be added by computing
1259 appropriate clock values.
1262 To prevent loss of data, AltOS provides receive and transmit
1263 fifos of 32 characters each.
1266 <title>ao_serial_getchar</title>
1269 ao_serial_getchar(void);
1272 Returns the next character from the receive fifo, blocking
1273 until a character is received if the fifo is empty.
1277 <title>ao_serial_putchar</title>
1280 ao_serial_putchar(char c);
1283 Adds a character to the transmit fifo, blocking if the
1284 fifo is full. Starts transmitting characters.
1288 <title>ao_serial_drain</title>
1291 ao_serial_drain(void);
1294 Blocks until the transmit fifo is empty. Used internally
1295 when changing serial speeds.
1299 <title>ao_serial_set_speed</title>
1302 ao_serial_set_speed(uint8_t speed);
1305 Changes the serial baud rate to one of
1306 AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or
1307 AO_SERIAL_SPEED_57600. This first flushes the transmit
1308 fifo using ao_serial_drain.
1312 <title>ao_serial_init</title>
1315 ao_serial_init(void)
1318 Initializes the serial peripheral. Call this from 'main'
1319 before jumping to ao_start_scheduler. The default speed
1320 setting is AO_SERIAL_SPEED_4800.
1325 <title>CC1111 Radio peripheral</title>
1327 The CC1111 radio transceiver sends and receives digital packets
1328 with forward error correction and detection. The AltOS driver is
1329 fairly specific to the needs of the TeleMetrum and TeleDongle
1330 devices, using it for other tasks may require customization of
1331 the driver itself. There are three basic modes of operation:
1335 Telemetry mode. In this mode, TeleMetrum transmits telemetry
1336 frames at a fixed rate. The frames are of fixed size. This
1337 is strictly a one-way communication from TeleMetrum to
1343 Packet mode. In this mode, the radio is used to create a
1344 reliable duplex byte stream between TeleDongle and
1345 TeleMetrum. This is an asymmetrical protocol with
1346 TeleMetrum only transmitting in response to a packet sent
1347 from TeleDongle. Thus getting data from TeleMetrum to
1348 TeleDongle requires polling. The polling rate is adaptive,
1349 when no data has been received for a while, the rate slows
1350 down. The packets are checked at both ends and invalid
1354 On the TeleMetrum side, the packet link is hooked into the
1355 stdio mechanism, providing an alternate data path for the
1356 command processor. It is enabled when the unit boots up in
1360 On the TeleDongle side, the packet link is enabled with a
1361 command; data from the stdio package is forwarded over the
1362 packet link providing a connection from the USB command
1363 stream to the remote TeleMetrum device.
1368 Radio Direction Finding mode. In this mode, TeleMetrum
1369 constructs a special packet that sounds like an audio tone
1370 when received by a conventional narrow-band FM
1371 receiver. This is designed to provide a beacon to track
1372 the device when other location mechanisms fail.
1378 <title>ao_radio_set_telemetry</title>
1381 ao_radio_set_telemetry(void);
1384 Configures the radio to send or receive telemetry
1385 packets. This includes packet length, modulation scheme and
1386 other RF parameters. It does not include the base frequency
1387 or channel though. Those are set at the time of transmission
1388 or reception, in case the values are changed by the user.
1392 <title>ao_radio_set_packet</title>
1395 ao_radio_set_packet(void);
1398 Configures the radio to send or receive packet data. This
1399 includes packet length, modulation scheme and other RF
1400 parameters. It does not include the base frequency or
1401 channel though. Those are set at the time of transmission or
1402 reception, in case the values are changed by the user.
1406 <title>ao_radio_set_rdf</title>
1409 ao_radio_set_rdf(void);
1412 Configures the radio to send RDF 'packets'. An RDF 'packet'
1413 is a sequence of hex 0x55 bytes sent at a base bit rate of
1414 2kbps using a 5kHz deviation. All of the error correction
1415 and data whitening logic is turned off so that the resulting
1416 modulation is received as a 1kHz tone by a conventional 70cm
1421 <title>ao_radio_idle</title>
1424 ao_radio_idle(void);
1427 Sets the radio device to idle mode, waiting until it reaches
1428 that state. This will terminate any in-progress transmit or
1433 <title>ao_radio_get</title>
1439 Acquires the radio mutex and then configures the radio
1440 frequency using the global radio calibration and channel
1445 <title>ao_radio_put</title>
1451 Releases the radio mutex.
1455 <title>ao_radio_abort</title>
1458 ao_radio_abort(void);
1461 Aborts any transmission or reception process by aborting the
1462 associated DMA object and calling ao_radio_idle to terminate
1463 the radio operation.
1467 In telemetry mode, you can send or receive a telemetry
1468 packet. The data from receiving a packet also includes the RSSI
1469 and status values supplied by the receiver. These are added
1470 after the telemetry data.
1473 <title>ao_radio_send</title>
1476 ao_radio_send(__xdata struct ao_telemetry *telemetry);
1479 This sends the specific telemetry packet, waiting for the
1480 transmission to complete. The radio must have been set to
1481 telemetry mode. This function calls ao_radio_get() before
1482 sending, and ao_radio_put() afterwards, to correctly
1483 serialize access to the radio device.
1487 <title>ao_radio_recv</title>
1490 ao_radio_recv(__xdata struct ao_radio_recv *radio);
1493 This blocks waiting for a telemetry packet to be received.
1494 The radio must have been set to telemetry mode. This
1495 function calls ao_radio_get() before receiving, and
1496 ao_radio_put() afterwards, to correctly serialize access
1497 to the radio device. This returns non-zero if a packet was
1498 received, or zero if the operation was aborted (from some
1499 other task calling ao_radio_abort()).
1503 In radio direction finding mode, there's just one function to
1507 <title>ao_radio_rdf</title>
1510 ao_radio_rdf(int ms);
1513 This sends an RDF packet lasting for the specified amount
1514 of time. The maximum length is 1020 ms.
1518 Packet mode is asymmetrical and is configured at compile time
1519 for either master or slave mode (but not both). The basic I/O
1520 functions look the same at both ends, but the internals are
1521 different, along with the initialization steps.
1524 <title>ao_packet_putchar</title>
1527 ao_packet_putchar(char c);
1530 If the output queue is full, this first blocks waiting for
1531 that data to be delivered. Then, queues a character for
1532 packet transmission. On the master side, this will
1533 transmit a packet if the output buffer is full. On the
1534 slave side, any pending data will be sent the next time
1535 the master polls for data.
1539 <title>ao_packet_pollchar</title>
1542 ao_packet_pollchar(void);
1545 This returns a pending input character if available,
1546 otherwise returns AO_READ_AGAIN. On the master side, if
1547 this empties the buffer, it triggers a poll for more data.
1551 <title>ao_packet_slave_start</title>
1554 ao_packet_slave_start(void);
1557 This is available only on the slave side and starts a task
1558 to listen for packet data.
1562 <title>ao_packet_slave_stop</title>
1565 ao_packet_slave_stop(void);
1568 Disables the packet slave task, stopping the radio receiver.
1572 <title>ao_packet_slave_init</title>
1575 ao_packet_slave_init(void);
1578 Adds the packet stdio functions to the stdio package so
1579 that when packet slave mode is enabled, characters will
1580 get send and received through the stdio functions.
1584 <title>ao_packet_master_init</title>
1587 ao_packet_master_init(void);
1590 Adds the 'p' packet forward command to start packet mode.
projects / fw / altos / blob