altos: Check for full log and complain
[fw/altos] / doc / altos.xsl
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">
4
5 <book>
6   <title>AltOS</title>
7   <subtitle>Altos Metrum Operating System</subtitle>
8   <bookinfo>
9     <author>
10       <firstname>Keith</firstname>
11       <surname>Packard</surname>
12     </author>
13     <copyright>
14       <year>2010</year>
15       <holder>Keith Packard</holder>
16     </copyright>
17     <legalnotice>
18       <para>
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
22         </ulink>
23         license.
24       </para>
25     </legalnotice>
26     <revhistory>
27       <revision>
28         <revnumber>0.1</revnumber>
29         <date>22 November 2010</date>
30         <revremark>Initial content</revremark>
31       </revision>
32     </revhistory>
33   </bookinfo>
34   <chapter>
35     <title>Overview</title>
36     <para>
37       AltOS is a operating system built for the 8051-compatible
38       processor found in the TI cc1111 microcontroller. It's designed
39       to be small and easy to program with. The main features are:
40       <itemizedlist>
41         <listitem>
42           <para>Multi-tasking. While the 8051 doesn't provide separate
43           address spaces, it's often easier to write code that operates
44           in separate threads instead of tying everything into one giant
45           event loop.
46           </para>
47         </listitem>
48         <listitem>
49           <para>Non-preemptive. This increases latency for thread
50           switching but reduces the number of places where context
51           switching can occur. It also simplifies the operating system
52           design somewhat. Nothing in the target system (rocket flight
53           control) has tight timing requirements, and so this seems like
54           a reasonable compromise.
55           </para>
56         </listitem>
57         <listitem>
58           <para>Sleep/wakeup scheduling. Taken directly from ancient
59           Unix designs, these two provide the fundemental scheduling
60           primitive within AltOS.
61           </para>
62         </listitem>
63         <listitem>
64           <para>Mutexes. As a locking primitive, mutexes are easier to
65           use than semaphores, at least in my experience.
66           </para>
67         </listitem>
68         <listitem>
69           <para>Timers. Tasks can set an alarm which will abort any
70           pending sleep, allowing operations to time-out instead of
71           blocking forever.
72           </para>
73         </listitem>
74       </itemizedlist>
75     </para>
76     <para>
77       The device drivers and other subsystems in AltOS are
78       conventionally enabled by invoking their _init() function from
79       the 'main' function before that calls
80       ao_start_scheduler(). These functions initialize the pin
81       assignments, add various commands to the command processor and
82       may add tasks to the scheduler to handle the device. A typical
83       main program, thus, looks like:
84       <programlisting>
85         void
86         main(void)
87         {
88                 ao_clock_init();
89
90                 /* Turn on the LED until the system is stable */
91                 ao_led_init(LEDS_AVAILABLE);
92                 ao_led_on(AO_LED_RED);
93                 ao_timer_init();
94                 ao_cmd_init();
95                 ao_usb_init();
96                 ao_monitor_init(AO_LED_GREEN, TRUE);
97                 ao_rssi_init(AO_LED_RED);
98                 ao_radio_init();
99                 ao_packet_slave_init();
100                 ao_packet_master_init();
101                 #if HAS_DBG
102                 ao_dbg_init();
103                 #endif
104                 ao_config_init();
105                 ao_start_scheduler();
106         }
107       </programlisting>
108       As you can see, a long sequence of subsystems are initialized
109       and then the scheduler is started.
110     </para>
111   </chapter>
112   <chapter>
113     <title>Programming the 8051 with SDCC</title>
114     <para>
115       The 8051 is a primitive 8-bit processor, designed in the mists
116       of time in as few transistors as possible. The architecture is
117       highly irregular and includes several separate memory
118       spaces. Furthermore, accessing stack variables is slow, and the
119       stack itself is of limited size. While SDCC papers over the
120       instruction set, it is not completely able to hide the memory
121       architecture from the application designer.
122     </para>
123     <section>
124       <title>8051 memory spaces</title>
125       <para>
126         The __data/__xdata/__code memory spaces below were completely
127         separate in the original 8051 design. In the cc1111, this
128         isn't true—they all live in a single unified 64kB address
129         space, and so it's possible to convert any address into a
130         unique 16-bit address. SDCC doesn't know this, and so a
131         'global' address to SDCC consumes 3 bytes of memory, 1 byte as
132         a tag indicating the memory space and 2 bytes of offset within
133         that space. AltOS avoids these 3-byte addresses as much as
134         possible; using them involves a function call per byte
135         access. The result is that nearly every variable declaration
136         is decorated with a memory space identifier which clutters the
137         code but makes the resulting code far smaller and more
138         efficient.
139       </para>
140       <section>
141         <title>__data</title>
142         <para>
143           The 8051 can directly address these 128 bytes of
144           memory. This makes them precious so they should be
145           reserved for frequently addressed values. Oh, just to
146           confuse things further, the 8 general registers in the
147           CPU are actually stored in this memory space. There are
148           magic instructions to 'bank switch' among 4 banks of
149           these registers located at 0x00 - 0x1F. AltOS uses only
150           the first bank at 0x00 - 0x07, leaving the other 24
151           bytes available for other data.
152         </para>
153       </section>
154       <section>
155         <title>__idata</title>
156         <para>
157           There are an additional 128 bytes of internal memory
158           that share the same address space as __data but which
159           cannot be directly addressed. The stack normally
160           occupies this space and so AltOS doesn't place any
161           static storage here.
162         </para>
163       </section>
164       <section>
165         <title>__xdata</title>
166         <para>
167           This is additional general memory accessed through a
168           single 16-bit address register. The CC1111F32 has 32kB
169           of memory available here. Most program data should live
170           in this memory space.
171         </para>
172       </section>
173       <section>
174         <title>__pdata</title>
175         <para>
176           This is an alias for the first 256 bytes of __xdata
177           memory, but uses a shorter addressing mode with
178           single global 8-bit value for the high 8 bits of the
179           address and any of several 8-bit registers for the low 8
180           bits. AltOS uses a few bits of this memory, it should
181           probably use more.
182         </para>
183       </section>
184       <section>
185         <title>__code</title>
186         <para>
187           All executable code must live in this address space, but
188           you can stick read-only data here too. It is addressed
189           using the 16-bit address register and special 'code'
190           access opcodes. Anything read-only should live in this space.
191         </para>
192       </section>
193       <section>
194         <title>__bit</title>
195         <para>
196           The 8051 has 128 bits of bit-addressible memory that
197           lives in the __data segment from 0x20 through
198           0x2f. Special instructions access these bits
199           in a single atomic operation. This isn't so much a
200           separate address space as a special addressing mode for
201           a few bytes in the __data segment.
202         </para>
203       </section>
204       <section>
205         <title>__sfr, __sfr16, __sfr32, __sbit</title>
206         <para>
207           Access to physical registers in the device use this mode
208           which declares the variable name, it's type and the
209           address it lives at. No memory is allocated for these
210           variables.
211         </para>
212       </section>
213     </section>
214     <section>
215       <title>Function calls on the 8051</title>
216       <para>
217         Because stack addressing is expensive, and stack space
218         limited, the default function call declaration in SDCC
219         allocates all parameters and local variables in static global
220         memory. Just like fortran. This makes these functions
221         non-reentrant, and also consume space for parameters and
222         locals even when they are not running. The benefit is smaller
223         code and faster execution.
224       </para>
225       <section>
226         <title>__reentrant functions</title>
227         <para>
228           All functions which are re-entrant, either due to recursion
229           or due to a potential context switch while executing, should
230           be marked as __reentrant so that their parameters and local
231           variables get allocated on the stack. This ensures that
232           these values are not overwritten by another invocation of
233           the function.
234         </para>
235         <para>
236           Functions which use significant amounts of space for
237           arguments and/or local variables and which are not often
238           invoked can also be marked as __reentrant. The resulting
239           code will be larger, but the savings in memory are
240           frequently worthwhile.
241         </para>
242       </section>
243       <section>
244         <title>Non __reentrant functions</title>
245         <para>
246           All parameters and locals in non-reentrant functions can
247           have data space decoration so that they are allocated in
248           __xdata, __pdata or __data space as desired. This can avoid
249           consuming __data space for infrequently used variables in
250           frequently used functions.
251         </para>
252         <para>
253           All library functions called by SDCC, including functions
254           for multiplying and dividing large data types, are
255           non-reentrant. Because of this, interrupt handlers must not
256           invoke any library functions, including the multiply and
257           divide code.
258         </para>
259       </section>
260       <section>
261         <title>__interrupt functions</title>
262         <para>
263           Interrupt functions are declared with with an __interrupt
264           decoration that includes the interrupt number. SDCC saves
265           and restores all of the registers in these functions and
266           uses the 'reti' instruction at the end so that they operate
267           as stand-alone interrupt handlers. Interrupt functions may
268           call the ao_wakeup function to wake AltOS tasks.
269         </para>
270       </section>
271       <section>
272         <title>__critical functions and statements</title>
273         <para>
274           SDCC has built-in support for suspending interrupts during
275           critical code. Functions marked as __critical will have
276           interrupts suspended for the whole period of
277           execution. Individual statements may also be marked as
278           __critical which blocks interrupts during the execution of
279           that statement. Keeping critical sections as short as
280           possible is key to ensuring that interrupts are handled as
281           quickly as possible.
282         </para>
283       </section>
284     </section>
285   </chapter>
286   <chapter>
287     <title>Task functions</title>
288     <para>
289       This chapter documents how to create, destroy and schedule AltOS tasks.
290     </para>
291     <section>
292       <title>ao_add_task</title>
293       <programlisting>
294         void
295         ao_add_task(__xdata struct ao_task * task,
296                     void (*start)(void),
297                     __code char *name);
298       </programlisting>
299       <para>
300         This initializes the statically allocated task structure,
301         assigns a name to it (not used for anything but the task
302         display), and the start address. It does not switch to the
303         new task. 'start' must not ever return; there is no place
304         to return to.
305       </para>
306     </section>
307     <section>
308       <title>ao_exit</title>
309       <programlisting>
310         void
311         ao_exit(void)
312       </programlisting>
313       <para>
314         This terminates the current task.
315       </para>
316     </section>
317     <section>
318       <title>ao_sleep</title>
319       <programlisting>
320         void
321         ao_sleep(__xdata void *wchan)
322       </programlisting>
323       <para>
324         This suspends the current task until 'wchan' is signaled
325         by ao_wakeup, or until the timeout, set by ao_alarm,
326         fires. If 'wchan' is signaled, ao_sleep returns 0, otherwise
327         it returns 1. This is the only way to switch to another task.
328       </para>
329       <para>
330         Because ao_wakeup wakes every task waiting on a particular
331         location, ao_sleep should be used in a loop that first
332         checks the desired condition, blocks in ao_sleep and then
333         rechecks until the condition is satisfied. If the
334         location may be signaled from an interrupt handler, the
335         code will need to block interrupts by using the __critical
336         label around the block of code. Here's a complete example:
337         <programlisting>
338           __critical while (!ao_radio_done)
339                   ao_sleep(&amp;ao_radio_done);
340         </programlisting>
341       </para>
342     </section>
343     <section>
344       <title>ao_wakeup</title>
345       <programlisting>
346         void
347         ao_wakeup(__xdata void *wchan)
348       </programlisting>
349       <para>
350         Wake all tasks blocked on 'wchan'. This makes them
351         available to be run again, but does not actually switch
352         to another task. Here's an example of using this:
353         <programlisting>
354           if (RFIF &amp; RFIF_IM_DONE) {
355                   ao_radio_done = 1;
356                   ao_wakeup(&amp;ao_radio_done);
357                   RFIF &amp;= ~RFIF_IM_DONE;
358           }
359         </programlisting>
360         Note that this need not be enclosed in __critical as the
361         ao_sleep block can only be run from normal mode, and so
362         this sequence can never be interrupted with execution of
363         the other sequence.
364       </para>
365     </section>
366     <section>
367       <title>ao_alarm</title>
368       <programlisting>
369         void
370         ao_alarm(uint16_t delay)
371       </programlisting>
372       <para>
373         Schedules an alarm to fire in at least 'delay' ticks. If
374         the task is asleep when the alarm fires, it will wakeup
375         and ao_sleep will return 1.
376         <programlisting>
377           ao_alarm(ao_packet_master_delay);
378           __critical while (!ao_radio_dma_done)
379                   if (ao_sleep(&amp;ao_radio_dma_done) != 0)
380                           ao_radio_abort();
381         </programlisting>
382         In this example, a timeout is set before waiting for
383         incoming radio data. If no data is received before the
384         timeout fires, ao_sleep will return 1 and then this code
385         will abort the radio receive operation.
386       </para>
387     </section>
388     <section>
389       <title>ao_wake_task</title>
390       <programlisting>
391         void
392         ao_wake_task(__xdata struct ao_task *task)
393       </programlisting>
394       <para>
395         Force a specific task to wake up, independent of which
396         'wchan' it is waiting for.
397       </para>
398     </section>
399     <section>
400       <title>ao_start_scheduler</title>
401       <programlisting>
402         void
403         ao_start_scheduler(void)
404       </programlisting>
405       <para>
406         This is called from 'main' when the system is all
407         initialized and ready to run. It will not return.
408       </para>
409     </section>
410     <section>
411       <title>ao_clock_init</title>
412       <programlisting>
413         void
414         ao_clock_init(void)
415       </programlisting>
416       <para>
417         This turns on the external 48MHz clock then switches the
418         hardware to using it. This is required by many of the
419         internal devices like USB. It should be called by the
420         'main' function first, before initializing any of the
421         other devices in the system.
422       </para>
423     </section>
424   </chapter>
425   <chapter>
426     <title>Timer Functions</title>
427     <para>
428       AltOS sets up one of the cc1111 timers to run at 100Hz and
429       exposes this tick as the fundemental unit of time. At each
430       interrupt, AltOS increments the counter, and schedules any tasks
431       waiting for that time to pass, then fires off the ADC system to
432       collect current data readings. Doing this from the ISR ensures
433       that the ADC values are sampled at a regular rate, independent
434       of any scheduling jitter.
435     </para>
436     <section>
437       <title>ao_time</title>
438       <programlisting>
439         uint16_t
440         ao_time(void)
441       </programlisting>
442       <para>
443         Returns the current system tick count. Note that this is
444         only a 16 bit value, and so it wraps every 655.36 seconds.
445       </para>
446     </section>
447     <section>
448       <title>ao_delay</title>
449       <programlisting>
450         void
451         ao_delay(uint16_t ticks);
452       </programlisting>
453       <para>
454         Suspend the current task for at least 'ticks' clock units.
455       </para>
456     </section>
457     <section>
458       <title>ao_timer_set_adc_interval</title>
459       <programlisting>
460         void
461         ao_timer_set_adc_interval(uint8_t interval);
462       </programlisting>
463       <para>
464         This sets the number of ticks between ADC samples. If set
465         to 0, no ADC samples are generated. AltOS uses this to
466         slow down the ADC sampling rate to save power.
467       </para>
468     </section>
469     <section>
470       <title>ao_timer_init</title>
471       <programlisting>
472         void
473         ao_timer_init(void)
474       </programlisting>
475       <para>
476         This turns on the 100Hz tick using the CC1111 timer 1. It
477         is required for any of the time-based functions to
478         work. It should be called by 'main' before ao_start_scheduler.
479       </para>
480     </section>
481   </chapter>
482   <chapter>
483     <title>AltOS Mutexes</title>
484     <para>
485       AltOS provides mutexes as a basic synchronization primitive. Each
486       mutexes is simply a byte of memory which holds 0 when the mutex
487       is free or the task id of the owning task when the mutex is
488       owned. Mutex calls are checked—attempting to acquire a mutex
489       already held by the current task or releasing a mutex not held
490       by the current task will both cause a panic.
491     </para>
492     <section>
493       <title>ao_mutex_get</title>
494       <programlisting>
495         void
496         ao_mutex_get(__xdata uint8_t *mutex);
497       </programlisting>
498       <para>
499         Acquires the specified mutex, blocking if the mutex is
500         owned by another task.
501       </para>
502     </section>
503     <section>
504       <title>ao_mutex_put</title>
505       <programlisting>
506         void
507         ao_mutex_put(__xdata uint8_t *mutex);
508       </programlisting>
509       <para>
510         Releases the specified mutex, waking up all tasks waiting
511         for it.
512       </para>
513     </section>
514   </chapter>
515   <chapter>
516     <title>CC1111 DMA engine</title>
517     <para>
518       The CC1111 contains a useful bit of extra hardware in the form
519       of five programmable DMA engines. They can be configured to copy
520       data in memory, or between memory and devices (or even between
521       two devices). AltOS exposes a general interface to this hardware
522       and uses it to handle radio and SPI data.
523     </para>
524     <para>
525       Code using a DMA engine should allocate one at startup
526       time. There is no provision to free them, and if you run out,
527       AltOS will simply panic.
528     </para>
529     <para>
530       During operation, the DMA engine is initialized with the
531       transfer parameters. Then it is started, at which point it
532       awaits a suitable event to start copying data. When copying data
533       from hardware to memory, that trigger event is supplied by the
534       hardware device. When copying data from memory to hardware, the
535       transfer is usually initiated by software.
536     </para>
537     <section>
538       <title>ao_dma_alloc</title>
539       <programlisting>
540         uint8_t
541         ao_dma_alloc(__xdata uint8_t *done)
542       </programlisting>
543       <para>
544         Allocates a DMA engine, returning the identifier. Whenever
545         this DMA engine completes a transfer. 'done' is cleared
546         when the DMA is started, and then receives the
547         AO_DMA_DONE bit on a successful transfer or the
548         AO_DMA_ABORTED bit if ao_dma_abort was called. Note that
549         it is possible to get both bits if the transfer was
550         aborted after it had finished.
551       </para>
552     </section>
553     <section>
554       <title>ao_dma_set_transfer</title>
555       <programlisting>
556         void
557         ao_dma_set_transfer(uint8_t id,
558                             void __xdata *srcaddr,
559                             void __xdata *dstaddr,
560                             uint16_t count,
561                             uint8_t cfg0,
562                             uint8_t cfg1)
563       </programlisting>
564       <para>
565         Initializes the specified dma engine to copy data
566         from 'srcaddr' to 'dstaddr' for 'count' units. cfg0 and
567         cfg1 are values directly out of the CC1111 documentation
568         and tell the DMA engine what the transfer unit size,
569         direction and step are.
570       </para>
571     </section>
572     <section>
573       <title>ao_dma_start</title>
574       <programlisting>
575         void
576         ao_dma_start(uint8_t id);
577       </programlisting>
578       <para>
579         Arm the specified DMA engine and await a signal from
580         either hardware or software to start transferring data.
581       </para>
582     </section>
583     <section>
584       <title>ao_dma_trigger</title>
585       <programlisting>
586         void
587         ao_dma_trigger(uint8_t id)
588       </programlisting>
589       <para>
590         Trigger the specified DMA engine to start copying data.
591       </para>
592     </section>
593     <section>
594       <title>ao_dma_abort</title>
595       <programlisting>
596         void
597         ao_dma_abort(uint8_t id)
598       </programlisting>
599       <para>
600         Terminate any in-progress DMA transation, marking its
601         'done' variable with the AO_DMA_ABORTED bit.
602       </para>
603     </section>
604   </chapter>
605   <chapter>
606     <title>SDCC Stdio interface</title>
607     <para>
608       AltOS offers a stdio interface over both USB and the RF packet
609       link. This provides for control of the device localy or
610       remotely. This is hooked up to the stdio functions in SDCC by
611       providing the standard putchar/getchar/flush functions. These
612       automatically multiplex the two available communication
613       channels; output is always delivered to the channel which
614       provided the most recent input.
615     </para>
616     <section>
617       <title>putchar</title>
618       <programlisting>
619         void
620         putchar(char c)
621       </programlisting>
622       <para>
623         Delivers a single character to the current console
624         device.
625       </para>
626     </section>
627     <section>
628       <title>getchar</title>
629       <programlisting>
630         char
631         getchar(void)
632       </programlisting>
633       <para>
634         Reads a single character from any of the available
635         console devices. The current console device is set to
636         that which delivered this character. This blocks until
637         a character is available.
638       </para>
639     </section>
640     <section>
641       <title>flush</title>
642       <programlisting>
643         void
644         flush(void)
645       </programlisting>
646       <para>
647         Flushes the current console device output buffer. Any
648         pending characters will be delivered to the target device.
649       xo          </para>
650     </section>
651     <section>
652       <title>ao_add_stdio</title>
653       <programlisting>
654         void
655         ao_add_stdio(char (*pollchar)(void),
656                            void (*putchar)(char),
657                            void (*flush)(void))
658       </programlisting>
659       <para>
660         This adds another console device to the available
661         list.
662       </para>
663       <para>
664         'pollchar' returns either an available character or
665         AO_READ_AGAIN if none is available. Significantly, it does
666         not block. The device driver must set 'ao_stdin_ready' to
667         1 and call ao_wakeup(&amp;ao_stdin_ready) when it receives
668         input to tell getchar that more data is available, at
669         which point 'pollchar' will be called again.
670       </para>
671       <para>
672         'putchar' queues a character for output, flushing if the output buffer is
673         full. It may block in this case.
674       </para>
675       <para>
676         'flush' forces the output buffer to be flushed. It may
677         block until the buffer is delivered, but it is not
678         required to do so.
679       </para>
680     </section>
681   </chapter>
682   <chapter>
683     <title>Command line interface</title>
684     <para>
685       AltOS includes a simple command line parser which is hooked up
686       to the stdio interfaces permitting remote control of the device
687       over USB or the RF link as desired. Each command uses a single
688       character to invoke it, the remaining characters on the line are
689       available as parameters to the command.
690     </para>
691     <section>
692       <title>ao_cmd_register</title>
693       <programlisting>
694         void
695         ao_cmd_register(__code struct ao_cmds *cmds)
696       </programlisting>
697       <para>
698         This registers a set of commands with the command
699         parser. There is a fixed limit on the number of command
700         sets, the system will panic if too many are registered.
701         Each command is defined by a struct ao_cmds entry:
702         <programlisting>
703           struct ao_cmds {
704                   char          cmd;
705                   void          (*func)(void);
706                   const char    *help;
707           };
708         </programlisting>
709         'cmd' is the character naming the command. 'func' is the
710         function to invoke and 'help' is a string displayed by the
711         '?' command. Syntax errors found while executing 'func'
712         should be indicated by modifying the global ao_cmd_status
713         variable with one of the following values:
714         <variablelist>
715           <varlistentry>
716             <title>ao_cmd_success</title>
717             <listitem>
718               <para>
719                 The command was parsed successfully. There is no
720                 need to assign this value, it is the default.
721               </para>
722             </listitem>
723           </varlistentry>
724           <varlistentry>
725             <title>ao_cmd_lex_error</title>
726             <listitem>
727               <para>
728                 A token in the line was invalid, such as a number
729                 containing invalid characters. The low-level
730                 lexing functions already assign this value as needed.
731               </para>
732             </listitem>
733           </varlistentry>
734           <varlistentry>
735             <title>ao_syntax_error</title>
736             <listitem>
737               <para>
738                 The command line is invalid for some reason other
739                 than invalid tokens.
740               </para>
741             </listitem>
742           </varlistentry>
743         </variablelist>
744       </para>
745     </section>
746     <section>
747       <title>ao_cmd_lex</title>
748       <programlisting>
749         void
750         ao_cmd_lex(void);
751       </programlisting>
752       <para>
753         This gets the next character out of the command line
754         buffer and sticks it into ao_cmd_lex_c. At the end of the
755         line, ao_cmd_lex_c will get a newline ('\n') character.
756       </para>
757     </section>
758     <section>
759       <title>ao_cmd_put16</title>
760       <programlisting>
761         void
762         ao_cmd_put16(uint16_t v);
763       </programlisting>
764       <para>
765         Writes 'v' as four hexadecimal characters.
766       </para>
767     </section>
768     <section>
769       <title>ao_cmd_put8</title>
770       <programlisting>
771         void
772         ao_cmd_put8(uint8_t v);
773       </programlisting>
774       <para>
775         Writes 'v' as two hexadecimal characters.
776       </para>
777     </section>
778     <section>
779       <title>ao_cmd_white</title>
780       <programlisting>
781         void
782         ao_cmd_white(void)
783       </programlisting>
784       <para>
785         This skips whitespace by calling ao_cmd_lex while
786         ao_cmd_lex_c is either a space or tab. It does not skip
787         any characters if ao_cmd_lex_c already non-white.
788       </para>
789     </section>
790     <section>
791       <title>ao_cmd_hex</title>
792       <programlisting>
793         void
794         ao_cmd_hex(void)
795       </programlisting>
796       <para>
797         This reads a 16-bit hexadecimal value from the command
798         line with optional leading whitespace. The resulting value
799         is stored in ao_cmd_lex_i;
800       </para>
801     </section>
802     <section>
803       <title>ao_cmd_decimal</title>
804       <programlisting>
805         void
806         ao_cmd_decimal(void)
807       </programlisting>
808       <para>
809         This reads a 32-bit decimal value from the command
810         line with optional leading whitespace. The resulting value
811         is stored in ao_cmd_lex_u32 and the low 16 bits are stored
812         in ao_cmd_lex_i;
813       </para>
814     </section>
815     <section>
816       <title>ao_match_word</title>
817       <programlisting>
818         uint8_t
819         ao_match_word(__code char *word)
820       </programlisting>
821       <para>
822         This checks to make sure that 'word' occurs on the command
823         line. It does not skip leading white space. If 'word' is
824         found, then 1 is returned. Otherwise, ao_cmd_status is set to
825         ao_cmd_syntax_error and 0 is returned.
826       </para>
827     </section>
828     <section>
829       <title>ao_cmd_init</title>
830       <programlisting>
831         void
832         ao_cmd_init(void
833       </programlisting>
834       <para>
835         Initializes the command system, setting up the built-in
836         commands and adding a task to run the command processing
837         loop. It should be called by 'main' before ao_start_scheduler.
838       </para>
839     </section>
840   </chapter>
841   <chapter>
842     <title>CC1111 USB target device</title>
843     <para>
844       The CC1111 contains a full-speed USB target device. It can be
845       programmed to offer any kind of USB target, but to simplify
846       interactions with a variety of operating systems, AltOS provides
847       only a single target device profile, that of a USB modem which
848       has native drivers for Linux, Windows and Mac OS X. It would be
849       easy to change the code to provide an alternate target device if
850       necessary.
851     </para>
852     <para>
853       To the rest of the system, the USB device looks like a simple
854       two-way byte stream. It can be hooked into the command line
855       interface if desired, offering control of the device over the
856       USB link. Alternatively, the functions can be accessed directly
857       to provide for USB-specific I/O.
858     </para>
859     <section>
860       <title>ao_usb_flush</title>
861       <programlisting>
862         void
863         ao_usb_flush(void);
864       </programlisting>
865       <para>
866         Flushes any pending USB output. This queues an 'IN' packet
867         to be delivered to the USB host if there is pending data,
868         or if the last IN packet was full to indicate to the host
869         that there isn't any more pending data available.
870       </para>
871     </section>
872     <section>
873       <title>ao_usb_putchar</title>
874       <programlisting>
875         void
876         ao_usb_putchar(char c);
877       </programlisting>
878       <para>
879         If there is a pending 'IN' packet awaiting delivery to the
880         host, this blocks until that has been fetched. Then, this
881         adds a byte to the pending IN packet for delivery to the
882         USB host. If the USB packet is full, this queues the 'IN'
883         packet for delivery.
884       </para>
885     </section>
886     <section>
887       <title>ao_usb_pollchar</title>
888       <programlisting>
889         char
890         ao_usb_pollchar(void);
891       </programlisting>
892       <para>
893         If there are no characters remaining in the last 'OUT'
894         packet received, this returns AO_READ_AGAIN. Otherwise, it
895         returns the next character, reporting to the host that it
896         is ready for more data when the last character is gone.
897       </para>
898     </section>
899     <section>
900       <title>ao_usb_getchar</title>
901       <programlisting>
902         char
903         ao_usb_getchar(void);
904       </programlisting>
905       <para>
906         This uses ao_pollchar to receive the next character,
907         blocking while ao_pollchar returns AO_READ_AGAIN.
908       </para>
909     </section>
910     <section>
911       <title>ao_usb_disable</title>
912       <programlisting>
913         void
914         ao_usb_disable(void);
915       </programlisting>
916       <para>
917         This turns off the USB controller. It will no longer
918         respond to host requests, nor return characters. Calling
919         any of the i/o routines while the USB device is disabled
920         is undefined, and likely to break things. Disabling the
921         USB device when not needed saves power.
922       </para>
923       <para>
924         Note that neither TeleDongle nor TeleMetrum are able to
925         signal to the USB host that they have disconnected, so
926         after disabling the USB device, it's likely that the cable
927         will need to be disconnected and reconnected before it
928         will work again.
929       </para>
930     </section>
931     <section>
932       <title>ao_usb_enable</title>
933       <programlisting>
934         void
935         ao_usb_enable(void);
936       </programlisting>
937       <para>
938         This turns the USB controller on again after it has been
939         disabled. See the note above about needing to physically
940         remove and re-insert the cable to get the host to
941         re-initialize the USB link.
942       </para>
943     </section>
944     <section>
945       <title>ao_usb_init</title>
946       <programlisting>
947         void
948         ao_usb_init(void);
949       </programlisting>
950       <para>
951         This turns the USB controller on, adds a task to handle
952         the control end point and adds the usb I/O functions to
953         the stdio system. Call this from main before
954         ao_start_scheduler.
955       </para>
956     </section>
957   </chapter>
958   <chapter>
959     <title>CC1111 Serial peripheral</title>
960     <para>
961       The CC1111 provides two USART peripherals. AltOS uses one for
962       asynch serial data, generally to communicate with a GPS device,
963       and the other for a SPI bus. The UART is configured to operate
964       in 8-bits, no parity, 1 stop bit framing. The default
965       configuration has clock settings for 4800, 9600 and 57600 baud
966       operation. Additional speeds can be added by computing
967       appropriate clock values.
968     </para>
969     <para>
970       To prevent loss of data, AltOS provides receive and transmit
971       fifos of 32 characters each.
972     </para>
973     <section>
974       <title>ao_serial_getchar</title>
975       <programlisting>
976         char
977         ao_serial_getchar(void);
978       </programlisting>
979       <para>
980         Returns the next character from the receive fifo, blocking
981         until a character is received if the fifo is empty.
982       </para>
983     </section>
984     <section>
985       <title>ao_serial_putchar</title>
986       <programlisting>
987         void
988         ao_serial_putchar(char c);
989       </programlisting>
990       <para>
991         Adds a character to the transmit fifo, blocking if the
992         fifo is full. Starts transmitting characters.
993       </para>
994     </section>
995     <section>
996       <title>ao_serial_drain</title>
997       <programlisting>
998         void
999         ao_serial_drain(void);
1000       </programlisting>
1001       <para>
1002         Blocks until the transmit fifo is empty. Used internally
1003         when changing serial speeds.
1004       </para>
1005     </section>
1006     <section>
1007       <title>ao_serial_set_speed</title>
1008       <programlisting>
1009         void
1010         ao_serial_set_speed(uint8_t speed);
1011       </programlisting>
1012       <para>
1013         Changes the serial baud rate to one of
1014         AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or
1015         AO_SERIAL_SPEED_57600. This first flushes the transmit
1016         fifo using ao_serial_drain.
1017       </para>
1018     </section>
1019     <section>
1020       <title>ao_serial_init</title>
1021       <programlisting>
1022         void
1023         ao_serial_init(void)
1024       </programlisting>
1025       <para>
1026         Initializes the serial peripheral. Call this from 'main'
1027         before jumping to ao_start_scheduler. The default speed
1028         setting is AO_SERIAL_SPEED_4800.
1029       </para>
1030     </section>
1031   </chapter>
1032   <chapter>
1033     <title>CC1111 Radio peripheral</title>
1034     <para>
1035       The CC1111 radio transceiver sends and receives digital packets
1036       with forward error correction and detection. The AltOS driver is
1037       fairly specific to the needs of the TeleMetrum and TeleDongle
1038       devices, using it for other tasks may require customization of
1039       the driver itself. There are three basic modes of operation:
1040       <orderedlist>
1041         <listitem>
1042           <para>
1043             Telemetry mode. In this mode, TeleMetrum transmits telemetry
1044             frames at a fixed rate. The frames are of fixed size. This
1045             is strictly a one-way communication from TeleMetrum to
1046             TeleDongle.
1047           </para>
1048         </listitem>
1049         <listitem>
1050           <para>
1051             Packet mode. In this mode, the radio is used to create a
1052             reliable duplex byte stream between TeleDongle and
1053             TeleMetrum. This is an asymmetrical protocol with
1054             TeleMetrum only transmitting in response to a packet sent
1055             from TeleDongle. Thus getting data from TeleMetrum to
1056             TeleDongle requires polling. The polling rate is adaptive,
1057             when no data has been received for a while, the rate slows
1058             down. The packets are checked at both ends and invalid
1059             data are ignored.
1060           </para>
1061           <para>
1062             On the TeleMetrum side, the packet link is hooked into the
1063             stdio mechanism, providing an alternate data path for the
1064             command processor. It is enabled when the unit boots up in
1065             'idle' mode.
1066           </para>
1067           <para>
1068             On the TeleDongle side, the packet link is enabled with a
1069             command; data from the stdio package is forwarded over the
1070             packet link providing a connection from the USB command
1071             stream to the remote TeleMetrum device.
1072           </para>
1073         </listitem>
1074         <listitem>
1075           <para>
1076             Radio Direction Finding mode. In this mode, TeleMetrum
1077             constructs a special packet that sounds like an audio tone
1078             when received by a conventional narrow-band FM
1079             receiver. This is designed to provide a beacon to track
1080             the device when other location mechanisms fail.
1081           </para>
1082         </listitem>
1083       </orderedlist>
1084     </para>
1085     <section>
1086       <title>ao_radio_set_telemetry</title>
1087         <programlisting>
1088           void
1089           ao_radio_set_telemetry(void);
1090         </programlisting>
1091         <para>
1092           Configures the radio to send or receive telemetry
1093           packets. This includes packet length, modulation scheme and
1094           other RF parameters. It does not include the base frequency
1095           or channel though. Those are set at the time of transmission
1096           or reception, in case the values are changed by the user.
1097         </para>
1098     </section>
1099     <section>
1100       <title>ao_radio_set_packet</title>
1101         <programlisting>
1102           void
1103           ao_radio_set_packet(void);
1104         </programlisting>
1105         <para>
1106           Configures the radio to send or receive packet data.  This
1107           includes packet length, modulation scheme and other RF
1108           parameters. It does not include the base frequency or
1109           channel though. Those are set at the time of transmission or
1110           reception, in case the values are changed by the user.
1111         </para>
1112     </section>
1113     <section>
1114       <title>ao_radio_set_rdf</title>
1115         <programlisting>
1116           void
1117           ao_radio_set_rdf(void);
1118         </programlisting>
1119         <para>
1120           Configures the radio to send RDF 'packets'. An RDF 'packet'
1121           is a sequence of hex 0x55 bytes sent at a base bit rate of
1122           2kbps using a 5kHz deviation. All of the error correction
1123           and data whitening logic is turned off so that the resulting
1124           modulation is received as a 1kHz tone by a conventional 70cm
1125           FM audio receiver.
1126         </para>
1127     </section>
1128     <section>
1129       <title>ao_radio_idle</title>
1130         <programlisting>
1131           void
1132           ao_radio_idle(void);
1133         </programlisting>
1134         <para>
1135           Sets the radio device to idle mode, waiting until it reaches
1136           that state. This will terminate any in-progress transmit or
1137           receive operation.
1138         </para>
1139     </section>
1140     <section>
1141       <title>ao_radio_get</title>
1142         <programlisting>
1143           void
1144           ao_radio_get(void);
1145         </programlisting>
1146         <para>
1147           Acquires the radio mutex and then configures the radio
1148           frequency using the global radio calibration and channel
1149           values.
1150         </para>
1151     </section>
1152     <section>
1153       <title>ao_radio_put</title>
1154         <programlisting>
1155           void
1156           ao_radio_put(void);
1157         </programlisting>
1158         <para>
1159           Releases the radio mutex.
1160         </para>
1161     </section>
1162     <section>
1163       <title>ao_radio_abort</title>
1164         <programlisting>
1165           void
1166           ao_radio_abort(void);
1167         </programlisting>
1168         <para>
1169           Aborts any transmission or reception process by aborting the
1170           associated DMA object and calling ao_radio_idle to terminate
1171           the radio operation.
1172         </para>
1173     </section>
1174     <para>
1175       In telemetry mode, you can send or receive a telemetry
1176       packet. The data from receiving a packet also includes the RSSI
1177       and status values supplied by the receiver. These are added
1178       after the telemetry data.
1179     </para>
1180     <section>
1181       <title>ao_radio_send</title>
1182         <programlisting>
1183           void
1184           ao_radio_send(__xdata struct ao_telemetry *telemetry);
1185         </programlisting>
1186         <para>
1187           This sends the specific telemetry packet, waiting for the
1188           transmission to complete. The radio must have been set to
1189           telemetry mode. This function calls ao_radio_get() before
1190           sending, and ao_radio_put() afterwards, to correctly
1191           serialize access to the radio device.
1192         </para>
1193     </section>
1194     <section>
1195       <title>ao_radio_recv</title>
1196         <programlisting>
1197           void
1198           ao_radio_recv(__xdata struct ao_radio_recv *radio);
1199         </programlisting>
1200         <para>
1201           This blocks waiting for a telemetry packet to be received.
1202           The radio must have been set to telemetry mode. This
1203           function calls ao_radio_get() before receiving, and
1204           ao_radio_put() afterwards, to correctly serialize access
1205           to the radio device. This returns non-zero if a packet was
1206           received, or zero if the operation was aborted (from some
1207           other task calling ao_radio_abort()).
1208         </para>
1209     </section>
1210     <para>
1211       In radio direction finding mode, there's just one function to
1212       use
1213     </para>
1214     <section>
1215       <title>ao_radio_rdf</title>
1216         <programlisting>
1217           void
1218           ao_radio_rdf(int ms);
1219         </programlisting>
1220         <para>
1221           This sends an RDF packet lasting for the specified amount
1222           of time. The maximum length is 1020 ms.
1223         </para>
1224     </section>
1225     <para>
1226       Packet mode is asymmetrical and is configured at compile time
1227       for either master or slave mode (but not both). The basic I/O
1228       functions look the same at both ends, but the internals are
1229       different, along with the initialization steps.
1230     </para>
1231     <section>
1232       <title>ao_packet_putchar</title>
1233         <programlisting>
1234           void
1235           ao_packet_putchar(char c);
1236         </programlisting>
1237         <para>
1238           If the output queue is full, this first blocks waiting for
1239           that data to be delivered. Then, queues a character for
1240           packet transmission. On the master side, this will
1241           transmit a packet if the output buffer is full. On the
1242           slave side, any pending data will be sent the next time
1243           the master polls for data.
1244         </para>
1245     </section>
1246     <section>
1247       <title>ao_packet_pollchar</title>
1248         <programlisting>
1249           char
1250           ao_packet_pollchar(void);
1251         </programlisting>
1252         <para>
1253           This returns a pending input character if available,
1254           otherwise returns AO_READ_AGAIN. On the master side, if
1255           this empties the buffer, it triggers a poll for more data.
1256         </para>
1257     </section>
1258     <section>
1259       <title>ao_packet_slave_start</title>
1260         <programlisting>
1261           void
1262           ao_packet_slave_start(void);
1263         </programlisting>
1264         <para>
1265           This is available only on the slave side and starts a task
1266           to listen for packet data.
1267         </para>
1268     </section>
1269     <section>
1270       <title>ao_packet_slave_stop</title>
1271         <programlisting>
1272           void
1273           ao_packet_slave_stop(void);
1274         </programlisting>
1275         <para>
1276           Disables the packet slave task, stopping the radio receiver.
1277         </para>
1278     </section>
1279     <section>
1280       <title>ao_packet_slave_init</title>
1281         <programlisting>
1282           void
1283           ao_packet_slave_init(void);
1284         </programlisting>
1285         <para>
1286           Adds the packet stdio functions to the stdio package so
1287           that when packet slave mode is enabled, characters will
1288           get send and received through the stdio functions.
1289         </para>
1290     </section>
1291     <section>
1292       <title>ao_packet_master_init</title>
1293         <programlisting>
1294           void
1295           ao_packet_master_init(void);
1296         </programlisting>
1297         <para>
1298           Adds the 'p' packet forward command to start packet mode.
1299         </para>
1300     </section>
1301   </chapter>
1302 </book>