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.
269 AO_EXTI_MODE_PULL_UP. Apply a pull-up to the pin; a
270 disconnected pin will read as 1.
275 AO_EXTI_MODE_PULL_DOWN. Apply a pull-down to the pin;
276 a disconnected pin will read as 0.
281 0. Don't apply either a pull-up or pull-down. A
282 disconnected pin will read an undetermined value.
290 <title>Reading and writing GPIO pins</title>
292 These macros read and write individual GPIO pins.
295 <title>ao_gpio_set</title>
297 #define ao_gpio_set(port, bit, pin, value)
300 Sets the specified port/bit or pin to the indicated value
304 <title>ao_gpio_get</title>
306 #define ao_gpio_get(port, bit, pin)
309 Returns either 1 or 0 depending on whether the input to
310 the pin is high or low.
317 <title>Programming the 8051 with SDCC</title>
319 The 8051 is a primitive 8-bit processor, designed in the mists
320 of time in as few transistors as possible. The architecture is
321 highly irregular and includes several separate memory
322 spaces. Furthermore, accessing stack variables is slow, and the
323 stack itself is of limited size. While SDCC papers over the
324 instruction set, it is not completely able to hide the memory
325 architecture from the application designer.
328 When built on other architectures, the various SDCC-specific
329 symbols are #defined as empty strings so they don't affect the compiler.
332 <title>8051 memory spaces</title>
334 The __data/__xdata/__code memory spaces below were completely
335 separate in the original 8051 design. In the cc1111, this
336 isn't true—they all live in a single unified 64kB address
337 space, and so it's possible to convert any address into a
338 unique 16-bit address. SDCC doesn't know this, and so a
339 'global' address to SDCC consumes 3 bytes of memory, 1 byte as
340 a tag indicating the memory space and 2 bytes of offset within
341 that space. AltOS avoids these 3-byte addresses as much as
342 possible; using them involves a function call per byte
343 access. The result is that nearly every variable declaration
344 is decorated with a memory space identifier which clutters the
345 code but makes the resulting code far smaller and more
349 <title>__data</title>
351 The 8051 can directly address these 128 bytes of
352 memory. This makes them precious so they should be
353 reserved for frequently addressed values. Oh, just to
354 confuse things further, the 8 general registers in the
355 CPU are actually stored in this memory space. There are
356 magic instructions to 'bank switch' among 4 banks of
357 these registers located at 0x00 - 0x1F. AltOS uses only
358 the first bank at 0x00 - 0x07, leaving the other 24
359 bytes available for other data.
363 <title>__idata</title>
365 There are an additional 128 bytes of internal memory
366 that share the same address space as __data but which
367 cannot be directly addressed. The stack normally
368 occupies this space and so AltOS doesn't place any
373 <title>__xdata</title>
375 This is additional general memory accessed through a
376 single 16-bit address register. The CC1111F32 has 32kB
377 of memory available here. Most program data should live
378 in this memory space.
382 <title>__pdata</title>
384 This is an alias for the first 256 bytes of __xdata
385 memory, but uses a shorter addressing mode with
386 single global 8-bit value for the high 8 bits of the
387 address and any of several 8-bit registers for the low 8
388 bits. AltOS uses a few bits of this memory, it should
393 <title>__code</title>
395 All executable code must live in this address space, but
396 you can stick read-only data here too. It is addressed
397 using the 16-bit address register and special 'code'
398 access opcodes. Anything read-only should live in this space.
404 The 8051 has 128 bits of bit-addressible memory that
405 lives in the __data segment from 0x20 through
406 0x2f. Special instructions access these bits
407 in a single atomic operation. This isn't so much a
408 separate address space as a special addressing mode for
409 a few bytes in the __data segment.
413 <title>__sfr, __sfr16, __sfr32, __sbit</title>
415 Access to physical registers in the device use this mode
416 which declares the variable name, it's type and the
417 address it lives at. No memory is allocated for these
423 <title>Function calls on the 8051</title>
425 Because stack addressing is expensive, and stack space
426 limited, the default function call declaration in SDCC
427 allocates all parameters and local variables in static global
428 memory. Just like fortran. This makes these functions
429 non-reentrant, and also consume space for parameters and
430 locals even when they are not running. The benefit is smaller
431 code and faster execution.
434 <title>__reentrant functions</title>
436 All functions which are re-entrant, either due to recursion
437 or due to a potential context switch while executing, should
438 be marked as __reentrant so that their parameters and local
439 variables get allocated on the stack. This ensures that
440 these values are not overwritten by another invocation of
444 Functions which use significant amounts of space for
445 arguments and/or local variables and which are not often
446 invoked can also be marked as __reentrant. The resulting
447 code will be larger, but the savings in memory are
448 frequently worthwhile.
452 <title>Non __reentrant functions</title>
454 All parameters and locals in non-reentrant functions can
455 have data space decoration so that they are allocated in
456 __xdata, __pdata or __data space as desired. This can avoid
457 consuming __data space for infrequently used variables in
458 frequently used functions.
461 All library functions called by SDCC, including functions
462 for multiplying and dividing large data types, are
463 non-reentrant. Because of this, interrupt handlers must not
464 invoke any library functions, including the multiply and
469 <title>__interrupt functions</title>
471 Interrupt functions are declared with with an __interrupt
472 decoration that includes the interrupt number. SDCC saves
473 and restores all of the registers in these functions and
474 uses the 'reti' instruction at the end so that they operate
475 as stand-alone interrupt handlers. Interrupt functions may
476 call the ao_wakeup function to wake AltOS tasks.
480 <title>__critical functions and statements</title>
482 SDCC has built-in support for suspending interrupts during
483 critical code. Functions marked as __critical will have
484 interrupts suspended for the whole period of
485 execution. Individual statements may also be marked as
486 __critical which blocks interrupts during the execution of
487 that statement. Keeping critical sections as short as
488 possible is key to ensuring that interrupts are handled as
489 quickly as possible. AltOS doesn't use this form in shared
490 code as other compilers wouldn't know what to do. Use
491 ao_arch_block_interrupts and ao_arch_release_interrupts instead.
497 <title>Task functions</title>
499 This chapter documents how to create, destroy and schedule AltOS tasks.
502 <title>ao_add_task</title>
505 ao_add_task(__xdata struct ao_task * task,
510 This initializes the statically allocated task structure,
511 assigns a name to it (not used for anything but the task
512 display), and the start address. It does not switch to the
513 new task. 'start' must not ever return; there is no place
518 <title>ao_exit</title>
524 This terminates the current task.
528 <title>ao_sleep</title>
531 ao_sleep(__xdata void *wchan)
534 This suspends the current task until 'wchan' is signaled
535 by ao_wakeup, or until the timeout, set by ao_alarm,
536 fires. If 'wchan' is signaled, ao_sleep returns 0, otherwise
537 it returns 1. This is the only way to switch to another task.
540 Because ao_wakeup wakes every task waiting on a particular
541 location, ao_sleep should be used in a loop that first checks
542 the desired condition, blocks in ao_sleep and then rechecks
543 until the condition is satisfied. If the location may be
544 signaled from an interrupt handler, the code will need to
545 block interrupts around the block of code. Here's a complete
548 ao_arch_block_interrupts();
549 while (!ao_radio_done)
550 ao_sleep(&ao_radio_done);
551 ao_arch_release_interrupts();
556 <title>ao_wakeup</title>
559 ao_wakeup(__xdata void *wchan)
562 Wake all tasks blocked on 'wchan'. This makes them
563 available to be run again, but does not actually switch
564 to another task. Here's an example of using this:
566 if (RFIF & RFIF_IM_DONE) {
568 ao_wakeup(&ao_radio_done);
569 RFIF &= ~RFIF_IM_DONE;
572 Note that this need not block interrupts as the ao_sleep block
573 can only be run from normal mode, and so this sequence can
574 never be interrupted with execution of the other sequence.
578 <title>ao_alarm</title>
581 ao_alarm(uint16_t delay);
584 ao_clear_alarm(void);
587 Schedules an alarm to fire in at least 'delay' ticks. If the
588 task is asleep when the alarm fires, it will wakeup and
589 ao_sleep will return 1. ao_clear_alarm resets any pending
590 alarm so that it doesn't fire at some arbitrary point in the
593 ao_alarm(ao_packet_master_delay);
594 ao_arch_block_interrupts();
595 while (!ao_radio_dma_done)
596 if (ao_sleep(&ao_radio_dma_done) != 0)
598 ao_arch_release_interrupts();
601 In this example, a timeout is set before waiting for
602 incoming radio data. If no data is received before the
603 timeout fires, ao_sleep will return 1 and then this code
604 will abort the radio receive operation.
608 <title>ao_start_scheduler</title>
611 ao_start_scheduler(void);
614 This is called from 'main' when the system is all
615 initialized and ready to run. It will not return.
619 <title>ao_clock_init</title>
625 This initializes the main CPU clock and switches to it.
630 <title>Timer Functions</title>
632 AltOS sets up one of the CPU timers to run at 100Hz and
633 exposes this tick as the fundemental unit of time. At each
634 interrupt, AltOS increments the counter, and schedules any tasks
635 waiting for that time to pass, then fires off the sensors to
636 collect current data readings. Doing this from the ISR ensures
637 that the values are sampled at a regular rate, independent
638 of any scheduling jitter.
641 <title>ao_time</title>
647 Returns the current system tick count. Note that this is
648 only a 16 bit value, and so it wraps every 655.36 seconds.
652 <title>ao_delay</title>
655 ao_delay(uint16_t ticks);
658 Suspend the current task for at least 'ticks' clock units.
662 <title>ao_timer_set_adc_interval</title>
665 ao_timer_set_adc_interval(uint8_t interval);
668 This sets the number of ticks between ADC samples. If set
669 to 0, no ADC samples are generated. AltOS uses this to
670 slow down the ADC sampling rate to save power.
674 <title>ao_timer_init</title>
680 This turns on the 100Hz tick. It is required for any of the
681 time-based functions to work. It should be called by 'main'
682 before ao_start_scheduler.
687 <title>AltOS Mutexes</title>
689 AltOS provides mutexes as a basic synchronization primitive. Each
690 mutexes is simply a byte of memory which holds 0 when the mutex
691 is free or the task id of the owning task when the mutex is
692 owned. Mutex calls are checked—attempting to acquire a mutex
693 already held by the current task or releasing a mutex not held
694 by the current task will both cause a panic.
697 <title>ao_mutex_get</title>
700 ao_mutex_get(__xdata uint8_t *mutex);
703 Acquires the specified mutex, blocking if the mutex is
704 owned by another task.
708 <title>ao_mutex_put</title>
711 ao_mutex_put(__xdata uint8_t *mutex);
714 Releases the specified mutex, waking up all tasks waiting
720 <title>DMA engine</title>
722 The CC1111 and STM32L both contain a useful bit of extra
723 hardware in the form of a number of programmable DMA
724 engines. They can be configured to copy data in memory, or
725 between memory and devices (or even between two devices). AltOS
726 exposes a general interface to this hardware and uses it to
727 handle both internal and external devices.
730 Because the CC1111 and STM32L DMA engines are different, the
731 interface to them is also different. As the DMA engines are
732 currently used to implement platform-specific drivers, this
736 Code using a DMA engine should allocate one at startup
737 time. There is no provision to free them, and if you run out,
738 AltOS will simply panic.
741 During operation, the DMA engine is initialized with the
742 transfer parameters. Then it is started, at which point it
743 awaits a suitable event to start copying data. When copying data
744 from hardware to memory, that trigger event is supplied by the
745 hardware device. When copying data from memory to hardware, the
746 transfer is usually initiated by software.
749 <title>CC1111 DMA Engine</title>
751 <title>ao_dma_alloc</title>
754 ao_dma_alloc(__xdata uint8_t *done)
757 Allocate a DMA engine, returning the identifier. 'done' is
758 cleared when the DMA is started, and then receives the
759 AO_DMA_DONE bit on a successful transfer or the
760 AO_DMA_ABORTED bit if ao_dma_abort was called. Note that it
761 is possible to get both bits if the transfer was aborted
762 after it had finished.
766 <title>ao_dma_set_transfer</title>
769 ao_dma_set_transfer(uint8_t id,
770 void __xdata *srcaddr,
771 void __xdata *dstaddr,
777 Initializes the specified dma engine to copy data
778 from 'srcaddr' to 'dstaddr' for 'count' units. cfg0 and
779 cfg1 are values directly out of the CC1111 documentation
780 and tell the DMA engine what the transfer unit size,
781 direction and step are.
785 <title>ao_dma_start</title>
788 ao_dma_start(uint8_t id);
791 Arm the specified DMA engine and await a signal from
792 either hardware or software to start transferring data.
796 <title>ao_dma_trigger</title>
799 ao_dma_trigger(uint8_t id)
802 Trigger the specified DMA engine to start copying data.
806 <title>ao_dma_abort</title>
809 ao_dma_abort(uint8_t id)
812 Terminate any in-progress DMA transation, marking its
813 'done' variable with the AO_DMA_ABORTED bit.
818 <title>STM32L DMA Engine</title>
820 <title>ao_dma_alloc</title>
822 uint8_t ao_dma_done[];
825 ao_dma_alloc(uint8_t index);
828 Reserve a DMA engine for exclusive use by one
833 <title>ao_dma_set_transfer</title>
836 ao_dma_set_transfer(uint8_t id,
843 Initializes the specified dma engine to copy data between
844 'peripheral' and 'memory' for 'count' units. 'ccr' is a
845 value directly out of the STM32L documentation and tells the
846 DMA engine what the transfer unit size, direction and step
851 <title>ao_dma_set_isr</title>
854 ao_dma_set_isr(uint8_t index, void (*isr)(int))
857 This sets a function to be called when the DMA transfer
858 completes in lieu of setting the ao_dma_done bits. Use this
859 when some work needs to be done when the DMA finishes that
860 cannot wait until user space resumes.
864 <title>ao_dma_start</title>
867 ao_dma_start(uint8_t id);
870 Arm the specified DMA engine and await a signal from either
871 hardware or software to start transferring data.
872 'ao_dma_done[index]' is cleared when the DMA is started, and
873 then receives the AO_DMA_DONE bit on a successful transfer
874 or the AO_DMA_ABORTED bit if ao_dma_abort was called. Note
875 that it is possible to get both bits if the transfer was
876 aborted after it had finished.
880 <title>ao_dma_done_transfer</title>
883 ao_dma_done_transfer(uint8_t id);
886 Signals that a specific DMA engine is done being used. This
887 allows multiple drivers to use the same DMA engine safely.
891 <title>ao_dma_abort</title>
894 ao_dma_abort(uint8_t id)
897 Terminate any in-progress DMA transation, marking its
898 'done' variable with the AO_DMA_ABORTED bit.
904 <title>Stdio interface</title>
906 AltOS offers a stdio interface over USB, serial and the RF
907 packet link. This provides for control of the device localy or
908 remotely. This is hooked up to the stdio functions by providing
909 the standard putchar/getchar/flush functions. These
910 automatically multiplex the available communication channels;
911 output is always delivered to the channel which provided the
915 <title>putchar</title>
921 Delivers a single character to the current console
926 <title>getchar</title>
932 Reads a single character from any of the available
933 console devices. The current console device is set to
934 that which delivered this character. This blocks until
935 a character is available.
945 Flushes the current console device output buffer. Any
946 pending characters will be delivered to the target device.
950 <title>ao_add_stdio</title>
953 ao_add_stdio(char (*pollchar)(void),
954 void (*putchar)(char),
958 This adds another console device to the available
962 'pollchar' returns either an available character or
963 AO_READ_AGAIN if none is available. Significantly, it does
964 not block. The device driver must set 'ao_stdin_ready' to
965 1 and call ao_wakeup(&ao_stdin_ready) when it receives
966 input to tell getchar that more data is available, at
967 which point 'pollchar' will be called again.
970 'putchar' queues a character for output, flushing if the output buffer is
971 full. It may block in this case.
974 'flush' forces the output buffer to be flushed. It may
975 block until the buffer is delivered, but it is not
981 <title>Command line interface</title>
983 AltOS includes a simple command line parser which is hooked up
984 to the stdio interfaces permitting remote control of the device
985 over USB, serial or the RF link as desired. Each command uses a
986 single character to invoke it, the remaining characters on the
987 line are available as parameters to the command.
990 <title>ao_cmd_register</title>
993 ao_cmd_register(__code struct ao_cmds *cmds)
996 This registers a set of commands with the command
997 parser. There is a fixed limit on the number of command
998 sets, the system will panic if too many are registered.
999 Each command is defined by a struct ao_cmds entry:
1007 'cmd' is the character naming the command. 'func' is the
1008 function to invoke and 'help' is a string displayed by the
1009 '?' command. Syntax errors found while executing 'func'
1010 should be indicated by modifying the global ao_cmd_status
1011 variable with one of the following values:
1014 <term>ao_cmd_success</term>
1017 The command was parsed successfully. There is no
1018 need to assign this value, it is the default.
1023 <term>ao_cmd_lex_error</term>
1026 A token in the line was invalid, such as a number
1027 containing invalid characters. The low-level
1028 lexing functions already assign this value as needed.
1033 <term>ao_syntax_error</term>
1036 The command line is invalid for some reason other
1037 than invalid tokens.
1045 <title>ao_cmd_lex</title>
1051 This gets the next character out of the command line
1052 buffer and sticks it into ao_cmd_lex_c. At the end of the
1053 line, ao_cmd_lex_c will get a newline ('\n') character.
1057 <title>ao_cmd_put16</title>
1060 ao_cmd_put16(uint16_t v);
1063 Writes 'v' as four hexadecimal characters.
1067 <title>ao_cmd_put8</title>
1070 ao_cmd_put8(uint8_t v);
1073 Writes 'v' as two hexadecimal characters.
1077 <title>ao_cmd_white</title>
1083 This skips whitespace by calling ao_cmd_lex while
1084 ao_cmd_lex_c is either a space or tab. It does not skip
1085 any characters if ao_cmd_lex_c already non-white.
1089 <title>ao_cmd_hex</title>
1095 This reads a 16-bit hexadecimal value from the command
1096 line with optional leading whitespace. The resulting value
1097 is stored in ao_cmd_lex_i;
1101 <title>ao_cmd_decimal</title>
1104 ao_cmd_decimal(void)
1107 This reads a 32-bit decimal value from the command
1108 line with optional leading whitespace. The resulting value
1109 is stored in ao_cmd_lex_u32 and the low 16 bits are stored
1114 <title>ao_match_word</title>
1117 ao_match_word(__code char *word)
1120 This checks to make sure that 'word' occurs on the command
1121 line. It does not skip leading white space. If 'word' is
1122 found, then 1 is returned. Otherwise, ao_cmd_status is set to
1123 ao_cmd_syntax_error and 0 is returned.
1127 <title>ao_cmd_init</title>
1133 Initializes the command system, setting up the built-in
1134 commands and adding a task to run the command processing
1135 loop. It should be called by 'main' before ao_start_scheduler.
1140 <title>USB target device</title>
1142 AltOS contains a full-speed USB target device driver. It can be
1143 programmed to offer any kind of USB target, but to simplify
1144 interactions with a variety of operating systems, AltOS provides
1145 only a single target device profile, that of a USB modem which
1146 has native drivers for Linux, Windows and Mac OS X. It would be
1147 easy to change the code to provide an alternate target device if
1151 To the rest of the system, the USB device looks like a simple
1152 two-way byte stream. It can be hooked into the command line
1153 interface if desired, offering control of the device over the
1154 USB link. Alternatively, the functions can be accessed directly
1155 to provide for USB-specific I/O.
1158 <title>ao_usb_flush</title>
1164 Flushes any pending USB output. This queues an 'IN' packet
1165 to be delivered to the USB host if there is pending data,
1166 or if the last IN packet was full to indicate to the host
1167 that there isn't any more pending data available.
1171 <title>ao_usb_putchar</title>
1174 ao_usb_putchar(char c);
1177 If there is a pending 'IN' packet awaiting delivery to the
1178 host, this blocks until that has been fetched. Then, this
1179 adds a byte to the pending IN packet for delivery to the
1180 USB host. If the USB packet is full, this queues the 'IN'
1181 packet for delivery.
1185 <title>ao_usb_pollchar</title>
1188 ao_usb_pollchar(void);
1191 If there are no characters remaining in the last 'OUT'
1192 packet received, this returns AO_READ_AGAIN. Otherwise, it
1193 returns the next character, reporting to the host that it
1194 is ready for more data when the last character is gone.
1198 <title>ao_usb_getchar</title>
1201 ao_usb_getchar(void);
1204 This uses ao_pollchar to receive the next character,
1205 blocking while ao_pollchar returns AO_READ_AGAIN.
1209 <title>ao_usb_disable</title>
1212 ao_usb_disable(void);
1215 This turns off the USB controller. It will no longer
1216 respond to host requests, nor return characters. Calling
1217 any of the i/o routines while the USB device is disabled
1218 is undefined, and likely to break things. Disabling the
1219 USB device when not needed saves power.
1222 Note that neither TeleDongle nor TeleMetrum are able to
1223 signal to the USB host that they have disconnected, so
1224 after disabling the USB device, it's likely that the cable
1225 will need to be disconnected and reconnected before it
1230 <title>ao_usb_enable</title>
1233 ao_usb_enable(void);
1236 This turns the USB controller on again after it has been
1237 disabled. See the note above about needing to physically
1238 remove and re-insert the cable to get the host to
1239 re-initialize the USB link.
1243 <title>ao_usb_init</title>
1249 This turns the USB controller on, adds a task to handle
1250 the control end point and adds the usb I/O functions to
1251 the stdio system. Call this from main before
1257 <title>Serial peripherals</title>
1259 The CC1111 provides two USART peripherals. AltOS uses one for
1260 asynch serial data, generally to communicate with a GPS device,
1261 and the other for a SPI bus. The UART is configured to operate
1262 in 8-bits, no parity, 1 stop bit framing. The default
1263 configuration has clock settings for 4800, 9600 and 57600 baud
1264 operation. Additional speeds can be added by computing
1265 appropriate clock values.
1268 To prevent loss of data, AltOS provides receive and transmit
1269 fifos of 32 characters each.
1272 <title>ao_serial_getchar</title>
1275 ao_serial_getchar(void);
1278 Returns the next character from the receive fifo, blocking
1279 until a character is received if the fifo is empty.
1283 <title>ao_serial_putchar</title>
1286 ao_serial_putchar(char c);
1289 Adds a character to the transmit fifo, blocking if the
1290 fifo is full. Starts transmitting characters.
1294 <title>ao_serial_drain</title>
1297 ao_serial_drain(void);
1300 Blocks until the transmit fifo is empty. Used internally
1301 when changing serial speeds.
1305 <title>ao_serial_set_speed</title>
1308 ao_serial_set_speed(uint8_t speed);
1311 Changes the serial baud rate to one of
1312 AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or
1313 AO_SERIAL_SPEED_57600. This first flushes the transmit
1314 fifo using ao_serial_drain.
1318 <title>ao_serial_init</title>
1321 ao_serial_init(void)
1324 Initializes the serial peripheral. Call this from 'main'
1325 before jumping to ao_start_scheduler. The default speed
1326 setting is AO_SERIAL_SPEED_4800.
1331 <title>CC1111 Radio peripheral</title>
1333 <title>Radio Introduction</title>
1335 The CC1111 radio transceiver sends and receives digital packets
1336 with forward error correction and detection. The AltOS driver is
1337 fairly specific to the needs of the TeleMetrum and TeleDongle
1338 devices, using it for other tasks may require customization of
1339 the driver itself. There are three basic modes of operation:
1343 Telemetry mode. In this mode, TeleMetrum transmits telemetry
1344 frames at a fixed rate. The frames are of fixed size. This
1345 is strictly a one-way communication from TeleMetrum to
1351 Packet mode. In this mode, the radio is used to create a
1352 reliable duplex byte stream between TeleDongle and
1353 TeleMetrum. This is an asymmetrical protocol with
1354 TeleMetrum only transmitting in response to a packet sent
1355 from TeleDongle. Thus getting data from TeleMetrum to
1356 TeleDongle requires polling. The polling rate is adaptive,
1357 when no data has been received for a while, the rate slows
1358 down. The packets are checked at both ends and invalid
1362 On the TeleMetrum side, the packet link is hooked into the
1363 stdio mechanism, providing an alternate data path for the
1364 command processor. It is enabled when the unit boots up in
1368 On the TeleDongle side, the packet link is enabled with a
1369 command; data from the stdio package is forwarded over the
1370 packet link providing a connection from the USB command
1371 stream to the remote TeleMetrum device.
1376 Radio Direction Finding mode. In this mode, TeleMetrum
1377 constructs a special packet that sounds like an audio tone
1378 when received by a conventional narrow-band FM
1379 receiver. This is designed to provide a beacon to track
1380 the device when other location mechanisms fail.
1387 <title>ao_radio_set_telemetry</title>
1390 ao_radio_set_telemetry(void);
1393 Configures the radio to send or receive telemetry
1394 packets. This includes packet length, modulation scheme and
1395 other RF parameters. It does not include the base frequency
1396 or channel though. Those are set at the time of transmission
1397 or reception, in case the values are changed by the user.
1401 <title>ao_radio_set_packet</title>
1404 ao_radio_set_packet(void);
1407 Configures the radio to send or receive packet data. This
1408 includes packet length, modulation scheme and other RF
1409 parameters. It does not include the base frequency or
1410 channel though. Those are set at the time of transmission or
1411 reception, in case the values are changed by the user.
1415 <title>ao_radio_set_rdf</title>
1418 ao_radio_set_rdf(void);
1421 Configures the radio to send RDF 'packets'. An RDF 'packet'
1422 is a sequence of hex 0x55 bytes sent at a base bit rate of
1423 2kbps using a 5kHz deviation. All of the error correction
1424 and data whitening logic is turned off so that the resulting
1425 modulation is received as a 1kHz tone by a conventional 70cm
1430 <title>ao_radio_idle</title>
1433 ao_radio_idle(void);
1436 Sets the radio device to idle mode, waiting until it reaches
1437 that state. This will terminate any in-progress transmit or
1442 <title>ao_radio_get</title>
1448 Acquires the radio mutex and then configures the radio
1449 frequency using the global radio calibration and channel
1454 <title>ao_radio_put</title>
1460 Releases the radio mutex.
1464 <title>ao_radio_abort</title>
1467 ao_radio_abort(void);
1470 Aborts any transmission or reception process by aborting the
1471 associated DMA object and calling ao_radio_idle to terminate
1472 the radio operation.
1476 <title>Radio Telemetry</title>
1478 In telemetry mode, you can send or receive a telemetry
1479 packet. The data from receiving a packet also includes the RSSI
1480 and status values supplied by the receiver. These are added
1481 after the telemetry data.
1484 <title>ao_radio_send</title>
1487 ao_radio_send(__xdata struct ao_telemetry *telemetry);
1490 This sends the specific telemetry packet, waiting for the
1491 transmission to complete. The radio must have been set to
1492 telemetry mode. This function calls ao_radio_get() before
1493 sending, and ao_radio_put() afterwards, to correctly
1494 serialize access to the radio device.
1498 <title>ao_radio_recv</title>
1501 ao_radio_recv(__xdata struct ao_radio_recv *radio);
1504 This blocks waiting for a telemetry packet to be received.
1505 The radio must have been set to telemetry mode. This
1506 function calls ao_radio_get() before receiving, and
1507 ao_radio_put() afterwards, to correctly serialize access
1508 to the radio device. This returns non-zero if a packet was
1509 received, or zero if the operation was aborted (from some
1510 other task calling ao_radio_abort()).
1515 <title>Radio Direction Finding</title>
1517 In radio direction finding mode, there's just one function to
1521 <title>ao_radio_rdf</title>
1524 ao_radio_rdf(int ms);
1527 This sends an RDF packet lasting for the specified amount
1528 of time. The maximum length is 1020 ms.
1533 <title>Radio Packet Mode</title>
1535 Packet mode is asymmetrical and is configured at compile time
1536 for either master or slave mode (but not both). The basic I/O
1537 functions look the same at both ends, but the internals are
1538 different, along with the initialization steps.
1541 <title>ao_packet_putchar</title>
1544 ao_packet_putchar(char c);
1547 If the output queue is full, this first blocks waiting for
1548 that data to be delivered. Then, queues a character for
1549 packet transmission. On the master side, this will
1550 transmit a packet if the output buffer is full. On the
1551 slave side, any pending data will be sent the next time
1552 the master polls for data.
1556 <title>ao_packet_pollchar</title>
1559 ao_packet_pollchar(void);
1562 This returns a pending input character if available,
1563 otherwise returns AO_READ_AGAIN. On the master side, if
1564 this empties the buffer, it triggers a poll for more data.
1568 <title>ao_packet_slave_start</title>
1571 ao_packet_slave_start(void);
1574 This is available only on the slave side and starts a task
1575 to listen for packet data.
1579 <title>ao_packet_slave_stop</title>
1582 ao_packet_slave_stop(void);
1585 Disables the packet slave task, stopping the radio receiver.
1589 <title>ao_packet_slave_init</title>
1592 ao_packet_slave_init(void);
1595 Adds the packet stdio functions to the stdio package so
1596 that when packet slave mode is enabled, characters will
1597 get send and received through the stdio functions.
1601 <title>ao_packet_master_init</title>
1604 ao_packet_master_init(void);
1607 Adds the 'p' packet forward command to start packet mode.
projects / fw / altos / blob