1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>AltOS</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" title="AltOS"><div class="titlepage"><div><div><h1 class="title"><a name="id2644500"></a>AltOS</h1></div><div><h2 class="subtitle">Altos Metrum Operating System</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Keith</span> <span class="surname">Packard</span></h3></div></div><div><p class="copyright">Copyright © 2010 Keith Packard</p></div><div><div class="legalnotice" title="Legal Notice"><a name="id2926184"></a><p>
This document is released under the terms of the
<a class="ulink" href="http://creativecommons.org/licenses/by-sa/3.0/" target="_top">
Creative Commons ShareAlike 3.0
</a>
license.
</p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision 0.1</td><td align="left">22 November 2010</td></tr><tr><td align="left" colspan="2">Initial content</td></tr></table></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#id2911956">1. Overview</a></span></dt><dt><span class="chapter"><a href="#id2935866">2. Programming the 8051 with SDCC</a></span></dt><dd><dl><dt><span class="section"><a href="#id2929311">8051 memory spaces</a></span></dt><dd><dl><dt><span class="section"><a href="#id2943908">__data</a></span></dt><dt><span class="section"><a href="#id2930844">__idata</a></span></dt><dt><span class="section"><a href="#id2942263">__xdata</a></span></dt><dt><span class="section"><a href="#id2925549">__pdata</a></span></dt><dt><span class="section"><a href="#id2921651">__code</a></span></dt><dt><span class="section"><a href="#id2927691">__bit</a></span></dt><dt><span class="section"><a href="#id2915402">__sfr, __sfr16, __sfr32, __sbit</a></span></dt></dl></dd><dt><span class="section"><a href="#id2921946">Function calls on the 8051</a></span></dt><dd><dl><dt><span class="section"><a href="#id2914273">__reentrant functions</a></span></dt><dt><span class="section"><a href="#id2915415">Non __reentrant functions</a></span></dt><dt><span class="section"><a href="#id2943768">__interrupt functions</a></span></dt><dt><span class="section"><a href="#id2927684">__critical functions and statements</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#id2935490">3. Task functions</a></span></dt><dd><dl><dt><span class="section"><a href="#id2923222">ao_add_task</a></span></dt><dt><span class="section"><a href="#id2906423">ao_exit</a></span></dt><dt><span class="section"><a href="#id2945624">ao_sleep</a></span></dt><dt><span class="section"><a href="#id2912516">ao_wakeup</a></span></dt><dt><span class="section"><a href="#id2935655">ao_alarm</a></span></dt><dt><span class="section"><a href="#id2922357">ao_start_scheduler</a></span></dt><dt><span class="section"><a href="#id2922493">ao_clock_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2928598">4. Timer Functions</a></span></dt><dd><dl><dt><span class="section"><a href="#id2921037">ao_time</a></span></dt><dt><span class="section"><a href="#id2931762">ao_delay</a></span></dt><dt><span class="section"><a href="#id2941318">ao_timer_set_adc_interval</a></span></dt><dt><span class="section"><a href="#id2942951">ao_timer_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2925949">5. AltOS Mutexes</a></span></dt><dd><dl><dt><span class="section"><a href="#id2920720">ao_mutex_get</a></span></dt><dt><span class="section"><a href="#id2921724">ao_mutex_put</a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2941985">6. CC1111 DMA engine</a></span></dt><dd><dl><dt><span class="section"><a href="#id2945111">ao_dma_alloc</a></span></dt><dt><span class="section"><a href="#id2906682">ao_dma_set_transfer</a></span></dt><dt><span class="section"><a href="#id2923449">ao_dma_start</a></span></dt><dt><span class="section"><a href="#id2924948">ao_dma_trigger</a></span></dt><dt><span class="section"><a href="#id2926755">ao_dma_abort</a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2922649">7. SDCC Stdio interface</a></span></dt><dd><dl><dt><span class="section"><a href="#id2939565">putchar</a></span></dt><dt><span class="section"><a href="#id2919239">getchar</a></span></dt><dt><span class="section"><a href="#id2936340">flush</a></span></dt><dt><span class="section"><a href="#id2919501">ao_add_stdio</a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2918389">8. Command line interface</a></span></dt><dd><dl><dt><span class="section"><a href="#id2946883">ao_cmd_register</a></span></dt><dt><span class="section"><a href="#id2936480">ao_cmd_lex</a></span></dt><dt><span class="section"><a href="#id2934898">ao_cmd_put16</a></span></dt><dt><span class="section"><a href="#id2946243">ao_cmd_put8</a></span></dt><dt><span class="section"><a href="#id2945885">ao_cmd_white</a></span></dt><dt><span class="section"><a href="#id2934349">ao_cmd_hex</a></span></dt><dt><span class="section"><a href="#id2944178">ao_cmd_decimal</a></span></dt><dt><span class="section"><a href="#id2942940">ao_match_word</a></span></dt><dt><span class="section"><a href="#id2940080">ao_cmd_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2921413">9. CC1111 USB target device</a></span></dt><dd><dl><dt><span class="section"><a href="#id2938680">ao_usb_flush</a></span></dt><dt><span class="section"><a href="#id2929550">ao_usb_putchar</a></span></dt><dt><span class="section"><a href="#id2921252">ao_usb_pollchar</a></span></dt><dt><span class="section"><a href="#id2928933">ao_usb_getchar</a></span></dt><dt><span class="section"><a href="#id2945790">ao_usb_disable</a></span></dt><dt><span class="section"><a href="#id2926157">ao_usb_enable</a></span></dt><dt><span class="section"><a href="#id2929728">ao_usb_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2940757">10. CC1111 Serial peripheral</a></span></dt><dd><dl><dt><span class="section"><a href="#id2935496">ao_serial_getchar</a></span></dt><dt><span class="section"><a href="#id2927850">ao_serial_putchar</a></span></dt><dt><span class="section"><a href="#id2939780">ao_serial_drain</a></span></dt><dt><span class="section"><a href="#id2935064">ao_serial_set_speed</a></span></dt><dt><span class="section"><a href="#id2910707">ao_serial_init</a></span></dt></dl></dd><dt><span class="chapter"><a href="#id2921332">11. CC1111 Radio peripheral</a></span></dt><dd><dl><dt><span class="section"><a href="#id2942652">ao_radio_set_telemetry</a></span></dt><dt><span class="section"><a href="#id2932868">ao_radio_set_packet</a></span></dt><dt><span class="section"><a href="#id2924450">ao_radio_set_rdf</a></span></dt><dt><span class="section"><a href="#id2929401">ao_radio_idle</a></span></dt><dt><span class="section"><a href="#id2939945">ao_radio_get</a></span></dt><dt><span class="section"><a href="#id2945270">ao_radio_put</a></span></dt><dt><span class="section"><a href="#id2940062">ao_radio_abort</a></span></dt><dt><span class="section"><a href="#id2935488">ao_radio_send</a></span></dt><dt><span class="section"><a href="#id2933204">ao_radio_recv</a></span></dt><dt><span class="section"><a href="#id2922259">ao_radio_rdf</a></span></dt><dt><span class="section"><a href="#id2933786">ao_packet_putchar</a></span></dt><dt><span class="section"><a href="#id2901174">ao_packet_pollchar</a></span></dt><dt><span class="section"><a href="#id2923629">ao_packet_slave_start</a></span></dt><dt><span class="section"><a href="#id2924465">ao_packet_slave_stop</a></span></dt><dt><span class="section"><a href="#id2930002">ao_packet_slave_init</a></span></dt><dt><span class="section"><a href="#id2929069">ao_packet_master_init</a></span></dt></dl></dd></dl></div><div class="chapter" title="Chapter 1. Overview"><div class="titlepage"><div><div><h2 class="title"><a name="id2911956"></a>Chapter 1. Overview</h2></div></div></div><p>
AltOS is a operating system built for the 8051-compatible
processor found in the TI cc1111 microcontroller. It's designed
to be small and easy to program with. The main features are:
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Multi-tasking. While the 8051 doesn't provide separate
address spaces, it's often easier to write code that operates
in separate threads instead of tying everything into one giant
event loop.
</p></li><li class="listitem"><p>Non-preemptive. This increases latency for thread
switching but reduces the number of places where context
switching can occur. It also simplifies the operating system
design somewhat. Nothing in the target system (rocket flight
control) has tight timing requirements, and so this seems like
a reasonable compromise.
</p></li><li class="listitem"><p>Sleep/wakeup scheduling. Taken directly from ancient
Unix designs, these two provide the fundemental scheduling
primitive within AltOS.
</p></li><li class="listitem"><p>Mutexes. As a locking primitive, mutexes are easier to
use than semaphores, at least in my experience.
</p></li><li class="listitem"><p>Timers. Tasks can set an alarm which will abort any
pending sleep, allowing operations to time-out instead of
blocking forever.
</p></li></ul></div><p>
</p><p>
The device drivers and other subsystems in AltOS are
conventionally enabled by invoking their _init() function from
the 'main' function before that calls
ao_start_scheduler(). These functions initialize the pin
assignments, add various commands to the command processor and
may add tasks to the scheduler to handle the device. A typical
main program, thus, looks like:
</p><pre class="programlisting">
void
main(void)
{
ao_clock_init();
/* Turn on the LED until the system is stable */
ao_led_init(LEDS_AVAILABLE);
ao_led_on(AO_LED_RED);
ao_timer_init();
ao_cmd_init();
ao_usb_init();
ao_monitor_init(AO_LED_GREEN, TRUE);
ao_rssi_init(AO_LED_RED);
ao_radio_init();
ao_packet_slave_init();
ao_packet_master_init();
#if HAS_DBG
ao_dbg_init();
#endif
ao_config_init();
ao_start_scheduler();
}
</pre><p>
As you can see, a long sequence of subsystems are initialized
and then the scheduler is started.
</p></div><div class="chapter" title="Chapter 2. Programming the 8051 with SDCC"><div class="titlepage"><div><div><h2 class="title"><a name="id2935866"></a>Chapter 2. Programming the 8051 with SDCC</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2929311">8051 memory spaces</a></span></dt><dd><dl><dt><span class="section"><a href="#id2943908">__data</a></span></dt><dt><span class="section"><a href="#id2930844">__idata</a></span></dt><dt><span class="section"><a href="#id2942263">__xdata</a></span></dt><dt><span class="section"><a href="#id2925549">__pdata</a></span></dt><dt><span class="section"><a href="#id2921651">__code</a></span></dt><dt><span class="section"><a href="#id2927691">__bit</a></span></dt><dt><span class="section"><a href="#id2915402">__sfr, __sfr16, __sfr32, __sbit</a></span></dt></dl></dd><dt><span class="section"><a href="#id2921946">Function calls on the 8051</a></span></dt><dd><dl><dt><span class="section"><a href="#id2914273">__reentrant functions</a></span></dt><dt><span class="section"><a href="#id2915415">Non __reentrant functions</a></span></dt><dt><span class="section"><a href="#id2943768">__interrupt functions</a></span></dt><dt><span class="section"><a href="#id2927684">__critical functions and statements</a></span></dt></dl></dd></dl></div><p>
The 8051 is a primitive 8-bit processor, designed in the mists
of time in as few transistors as possible. The architecture is
highly irregular and includes several separate memory
spaces. Furthermore, accessing stack variables is slow, and the
stack itself is of limited size. While SDCC papers over the
instruction set, it is not completely able to hide the memory
architecture from the application designer.
</p><div class="section" title="8051 memory spaces"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929311"></a>8051 memory spaces</h2></div></div></div><p>
The __data/__xdata/__code memory spaces below were completely
separate in the original 8051 design. In the cc1111, this
isn't true—they all live in a single unified 64kB address
space, and so it's possible to convert any address into a
unique 16-bit address. SDCC doesn't know this, and so a
'global' address to SDCC consumes 3 bytes of memory, 1 byte as
a tag indicating the memory space and 2 bytes of offset within
that space. AltOS avoids these 3-byte addresses as much as
possible; using them involves a function call per byte
access. The result is that nearly every variable declaration
is decorated with a memory space identifier which clutters the
code but makes the resulting code far smaller and more
efficient.
</p><div class="section" title="__data"><div class="titlepage"><div><div><h3 class="title"><a name="id2943908"></a>__data</h3></div></div></div><p>
The 8051 can directly address these 128 bytes of
memory. This makes them precious so they should be
reserved for frequently addressed values. Oh, just to
confuse things further, the 8 general registers in the
CPU are actually stored in this memory space. There are
magic instructions to 'bank switch' among 4 banks of
these registers located at 0x00 - 0x1F. AltOS uses only
the first bank at 0x00 - 0x07, leaving the other 24
bytes available for other data.
</p></div><div class="section" title="__idata"><div class="titlepage"><div><div><h3 class="title"><a name="id2930844"></a>__idata</h3></div></div></div><p>
There are an additional 128 bytes of internal memory
that share the same address space as __data but which
cannot be directly addressed. The stack normally
occupies this space and so AltOS doesn't place any
static storage here.
</p></div><div class="section" title="__xdata"><div class="titlepage"><div><div><h3 class="title"><a name="id2942263"></a>__xdata</h3></div></div></div><p>
This is additional general memory accessed through a
single 16-bit address register. The CC1111F32 has 32kB
of memory available here. Most program data should live
in this memory space.
</p></div><div class="section" title="__pdata"><div class="titlepage"><div><div><h3 class="title"><a name="id2925549"></a>__pdata</h3></div></div></div><p>
This is an alias for the first 256 bytes of __xdata
memory, but uses a shorter addressing mode with
single global 8-bit value for the high 8 bits of the
address and any of several 8-bit registers for the low 8
bits. AltOS uses a few bits of this memory, it should
probably use more.
</p></div><div class="section" title="__code"><div class="titlepage"><div><div><h3 class="title"><a name="id2921651"></a>__code</h3></div></div></div><p>
All executable code must live in this address space, but
you can stick read-only data here too. It is addressed
using the 16-bit address register and special 'code'
access opcodes. Anything read-only should live in this space.
</p></div><div class="section" title="__bit"><div class="titlepage"><div><div><h3 class="title"><a name="id2927691"></a>__bit</h3></div></div></div><p>
The 8051 has 128 bits of bit-addressible memory that
lives in the __data segment from 0x20 through
0x2f. Special instructions access these bits
in a single atomic operation. This isn't so much a
separate address space as a special addressing mode for
a few bytes in the __data segment.
</p></div><div class="section" title="__sfr, __sfr16, __sfr32, __sbit"><div class="titlepage"><div><div><h3 class="title"><a name="id2915402"></a>__sfr, __sfr16, __sfr32, __sbit</h3></div></div></div><p>
Access to physical registers in the device use this mode
which declares the variable name, it's type and the
address it lives at. No memory is allocated for these
variables.
</p></div></div><div class="section" title="Function calls on the 8051"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2921946"></a>Function calls on the 8051</h2></div></div></div><p>
Because stack addressing is expensive, and stack space
limited, the default function call declaration in SDCC
allocates all parameters and local variables in static global
memory. Just like fortran. This makes these functions
non-reentrant, and also consume space for parameters and
locals even when they are not running. The benefit is smaller
code and faster execution.
</p><div class="section" title="__reentrant functions"><div class="titlepage"><div><div><h3 class="title"><a name="id2914273"></a>__reentrant functions</h3></div></div></div><p>
All functions which are re-entrant, either due to recursion
or due to a potential context switch while executing, should
be marked as __reentrant so that their parameters and local
variables get allocated on the stack. This ensures that
these values are not overwritten by another invocation of
the function.
</p><p>
Functions which use significant amounts of space for
arguments and/or local variables and which are not often
invoked can also be marked as __reentrant. The resulting
code will be larger, but the savings in memory are
frequently worthwhile.
</p></div><div class="section" title="Non __reentrant functions"><div class="titlepage"><div><div><h3 class="title"><a name="id2915415"></a>Non __reentrant functions</h3></div></div></div><p>
All parameters and locals in non-reentrant functions can
have data space decoration so that they are allocated in
__xdata, __pdata or __data space as desired. This can avoid
consuming __data space for infrequently used variables in
frequently used functions.
</p><p>
All library functions called by SDCC, including functions
for multiplying and dividing large data types, are
non-reentrant. Because of this, interrupt handlers must not
invoke any library functions, including the multiply and
divide code.
</p></div><div class="section" title="__interrupt functions"><div class="titlepage"><div><div><h3 class="title"><a name="id2943768"></a>__interrupt functions</h3></div></div></div><p>
Interrupt functions are declared with with an __interrupt
decoration that includes the interrupt number. SDCC saves
and restores all of the registers in these functions and
uses the 'reti' instruction at the end so that they operate
as stand-alone interrupt handlers. Interrupt functions may
call the ao_wakeup function to wake AltOS tasks.
</p></div><div class="section" title="__critical functions and statements"><div class="titlepage"><div><div><h3 class="title"><a name="id2927684"></a>__critical functions and statements</h3></div></div></div><p>
SDCC has built-in support for suspending interrupts during
critical code. Functions marked as __critical will have
interrupts suspended for the whole period of
execution. Individual statements may also be marked as
__critical which blocks interrupts during the execution of
that statement. Keeping critical sections as short as
possible is key to ensuring that interrupts are handled as
quickly as possible.
</p></div></div></div><div class="chapter" title="Chapter 3. Task functions"><div class="titlepage"><div><div><h2 class="title"><a name="id2935490"></a>Chapter 3. Task functions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2923222">ao_add_task</a></span></dt><dt><span class="section"><a href="#id2906423">ao_exit</a></span></dt><dt><span class="section"><a href="#id2945624">ao_sleep</a></span></dt><dt><span class="section"><a href="#id2912516">ao_wakeup</a></span></dt><dt><span class="section"><a href="#id2935655">ao_alarm</a></span></dt><dt><span class="section"><a href="#id2922357">ao_start_scheduler</a></span></dt><dt><span class="section"><a href="#id2922493">ao_clock_init</a></span></dt></dl></div><p>
This chapter documents how to create, destroy and schedule AltOS tasks.
</p><div class="section" title="ao_add_task"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2923222"></a>ao_add_task</h2></div></div></div><pre class="programlisting">
void
ao_add_task(__xdata struct ao_task * task,
void (*start)(void),
__code char *name);
</pre><p>
This initializes the statically allocated task structure,
assigns a name to it (not used for anything but the task
display), and the start address. It does not switch to the
new task. 'start' must not ever return; there is no place
to return to.
</p></div><div class="section" title="ao_exit"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2906423"></a>ao_exit</h2></div></div></div><pre class="programlisting">
void
ao_exit(void)
</pre><p>
This terminates the current task.
</p></div><div class="section" title="ao_sleep"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2945624"></a>ao_sleep</h2></div></div></div><pre class="programlisting">
void
ao_sleep(__xdata void *wchan)
</pre><p>
This suspends the current task until 'wchan' is signaled
by ao_wakeup, or until the timeout, set by ao_alarm,
fires. If 'wchan' is signaled, ao_sleep returns 0, otherwise
it returns 1. This is the only way to switch to another task.
</p><p>
Because ao_wakeup wakes every task waiting on a particular
location, ao_sleep should be used in a loop that first
checks the desired condition, blocks in ao_sleep and then
rechecks until the condition is satisfied. If the
location may be signaled from an interrupt handler, the
code will need to block interrupts by using the __critical
label around the block of code. Here's a complete example:
</p><pre class="programlisting">
__critical while (!ao_radio_done)
ao_sleep(&ao_radio_done);
</pre><p>
</p></div><div class="section" title="ao_wakeup"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2912516"></a>ao_wakeup</h2></div></div></div><pre class="programlisting">
void
ao_wakeup(__xdata void *wchan)
</pre><p>
Wake all tasks blocked on 'wchan'. This makes them
available to be run again, but does not actually switch
to another task. Here's an example of using this:
</p><pre class="programlisting">
if (RFIF & RFIF_IM_DONE) {
ao_radio_done = 1;
ao_wakeup(&ao_radio_done);
RFIF &= ~RFIF_IM_DONE;
}
</pre><p>
Note that this need not be enclosed in __critical as the
ao_sleep block can only be run from normal mode, and so
this sequence can never be interrupted with execution of
the other sequence.
</p></div><div class="section" title="ao_alarm"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2935655"></a>ao_alarm</h2></div></div></div><pre class="programlisting">
void
ao_alarm(uint16_t delay)
</pre><p>
Schedules an alarm to fire in at least 'delay' ticks. If
the task is asleep when the alarm fires, it will wakeup
and ao_sleep will return 1.
</p><pre class="programlisting">
ao_alarm(ao_packet_master_delay);
__critical while (!ao_radio_dma_done)
if (ao_sleep(&ao_radio_dma_done) != 0)
ao_radio_abort();
</pre><p>
In this example, a timeout is set before waiting for
incoming radio data. If no data is received before the
timeout fires, ao_sleep will return 1 and then this code
will abort the radio receive operation.
</p></div><div class="section" title="ao_start_scheduler"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2922357"></a>ao_start_scheduler</h2></div></div></div><pre class="programlisting">
void
ao_start_scheduler(void)
</pre><p>
This is called from 'main' when the system is all
initialized and ready to run. It will not return.
</p></div><div class="section" title="ao_clock_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2922493"></a>ao_clock_init</h2></div></div></div><pre class="programlisting">
void
ao_clock_init(void)
</pre><p>
This turns on the external 48MHz clock then switches the
hardware to using it. This is required by many of the
internal devices like USB. It should be called by the
'main' function first, before initializing any of the
other devices in the system.
</p></div></div><div class="chapter" title="Chapter 4. Timer Functions"><div class="titlepage"><div><div><h2 class="title"><a name="id2928598"></a>Chapter 4. Timer Functions</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2921037">ao_time</a></span></dt><dt><span class="section"><a href="#id2931762">ao_delay</a></span></dt><dt><span class="section"><a href="#id2941318">ao_timer_set_adc_interval</a></span></dt><dt><span class="section"><a href="#id2942951">ao_timer_init</a></span></dt></dl></div><p>
AltOS sets up one of the cc1111 timers to run at 100Hz and
exposes this tick as the fundemental unit of time. At each
interrupt, AltOS increments the counter, and schedules any tasks
waiting for that time to pass, then fires off the ADC system to
collect current data readings. Doing this from the ISR ensures
that the ADC values are sampled at a regular rate, independent
of any scheduling jitter.
</p><div class="section" title="ao_time"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2921037"></a>ao_time</h2></div></div></div><pre class="programlisting">
uint16_t
ao_time(void)
</pre><p>
Returns the current system tick count. Note that this is
only a 16 bit value, and so it wraps every 655.36 seconds.
</p></div><div class="section" title="ao_delay"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2931762"></a>ao_delay</h2></div></div></div><pre class="programlisting">
void
ao_delay(uint16_t ticks);
</pre><p>
Suspend the current task for at least 'ticks' clock units.
</p></div><div class="section" title="ao_timer_set_adc_interval"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2941318"></a>ao_timer_set_adc_interval</h2></div></div></div><pre class="programlisting">
void
ao_timer_set_adc_interval(uint8_t interval);
</pre><p>
This sets the number of ticks between ADC samples. If set
to 0, no ADC samples are generated. AltOS uses this to
slow down the ADC sampling rate to save power.
</p></div><div class="section" title="ao_timer_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2942951"></a>ao_timer_init</h2></div></div></div><pre class="programlisting">
void
ao_timer_init(void)
</pre><p>
This turns on the 100Hz tick using the CC1111 timer 1. It
is required for any of the time-based functions to
work. It should be called by 'main' before ao_start_scheduler.
</p></div></div><div class="chapter" title="Chapter 5. AltOS Mutexes"><div class="titlepage"><div><div><h2 class="title"><a name="id2925949"></a>Chapter 5. AltOS Mutexes</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2920720">ao_mutex_get</a></span></dt><dt><span class="section"><a href="#id2921724">ao_mutex_put</a></span></dt></dl></div><p>
AltOS provides mutexes as a basic synchronization primitive. Each
mutexes is simply a byte of memory which holds 0 when the mutex
is free or the task id of the owning task when the mutex is
owned. Mutex calls are checked—attempting to acquire a mutex
already held by the current task or releasing a mutex not held
by the current task will both cause a panic.
</p><div class="section" title="ao_mutex_get"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2920720"></a>ao_mutex_get</h2></div></div></div><pre class="programlisting">
void
ao_mutex_get(__xdata uint8_t *mutex);
</pre><p>
Acquires the specified mutex, blocking if the mutex is
owned by another task.
</p></div><div class="section" title="ao_mutex_put"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2921724"></a>ao_mutex_put</h2></div></div></div><pre class="programlisting">
void
ao_mutex_put(__xdata uint8_t *mutex);
</pre><p>
Releases the specified mutex, waking up all tasks waiting
for it.
</p></div></div><div class="chapter" title="Chapter 6. CC1111 DMA engine"><div class="titlepage"><div><div><h2 class="title"><a name="id2941985"></a>Chapter 6. CC1111 DMA engine</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2945111">ao_dma_alloc</a></span></dt><dt><span class="section"><a href="#id2906682">ao_dma_set_transfer</a></span></dt><dt><span class="section"><a href="#id2923449">ao_dma_start</a></span></dt><dt><span class="section"><a href="#id2924948">ao_dma_trigger</a></span></dt><dt><span class="section"><a href="#id2926755">ao_dma_abort</a></span></dt></dl></div><p>
The CC1111 contains a useful bit of extra hardware in the form
of five programmable DMA engines. They can be configured to copy
data in memory, or between memory and devices (or even between
two devices). AltOS exposes a general interface to this hardware
and uses it to handle radio and SPI data.
</p><p>
Code using a DMA engine should allocate one at startup
time. There is no provision to free them, and if you run out,
AltOS will simply panic.
</p><p>
During operation, the DMA engine is initialized with the
transfer parameters. Then it is started, at which point it
awaits a suitable event to start copying data. When copying data
from hardware to memory, that trigger event is supplied by the
hardware device. When copying data from memory to hardware, the
transfer is usually initiated by software.
</p><div class="section" title="ao_dma_alloc"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2945111"></a>ao_dma_alloc</h2></div></div></div><pre class="programlisting">
uint8_t
ao_dma_alloc(__xdata uint8_t *done)
</pre><p>
Allocates a DMA engine, returning the identifier. Whenever
this DMA engine completes a transfer. 'done' is cleared
when the DMA is started, and then receives the
AO_DMA_DONE bit on a successful transfer or the
AO_DMA_ABORTED bit if ao_dma_abort was called. Note that
it is possible to get both bits if the transfer was
aborted after it had finished.
</p></div><div class="section" title="ao_dma_set_transfer"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2906682"></a>ao_dma_set_transfer</h2></div></div></div><pre class="programlisting">
void
ao_dma_set_transfer(uint8_t id,
void __xdata *srcaddr,
void __xdata *dstaddr,
uint16_t count,
uint8_t cfg0,
uint8_t cfg1)
</pre><p>
Initializes the specified dma engine to copy data
from 'srcaddr' to 'dstaddr' for 'count' units. cfg0 and
cfg1 are values directly out of the CC1111 documentation
and tell the DMA engine what the transfer unit size,
direction and step are.
</p></div><div class="section" title="ao_dma_start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2923449"></a>ao_dma_start</h2></div></div></div><pre class="programlisting">
void
ao_dma_start(uint8_t id);
</pre><p>
Arm the specified DMA engine and await a signal from
either hardware or software to start transferring data.
</p></div><div class="section" title="ao_dma_trigger"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2924948"></a>ao_dma_trigger</h2></div></div></div><pre class="programlisting">
void
ao_dma_trigger(uint8_t id)
</pre><p>
Trigger the specified DMA engine to start copying data.
</p></div><div class="section" title="ao_dma_abort"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2926755"></a>ao_dma_abort</h2></div></div></div><pre class="programlisting">
void
ao_dma_abort(uint8_t id)
</pre><p>
Terminate any in-progress DMA transation, marking its
'done' variable with the AO_DMA_ABORTED bit.
</p></div></div><div class="chapter" title="Chapter 7. SDCC Stdio interface"><div class="titlepage"><div><div><h2 class="title"><a name="id2922649"></a>Chapter 7. SDCC Stdio interface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2939565">putchar</a></span></dt><dt><span class="section"><a href="#id2919239">getchar</a></span></dt><dt><span class="section"><a href="#id2936340">flush</a></span></dt><dt><span class="section"><a href="#id2919501">ao_add_stdio</a></span></dt></dl></div><p>
AltOS offers a stdio interface over both USB and the RF packet
link. This provides for control of the device localy or
remotely. This is hooked up to the stdio functions in SDCC by
providing the standard putchar/getchar/flush functions. These
automatically multiplex the two available communication
channels; output is always delivered to the channel which
provided the most recent input.
</p><div class="section" title="putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2939565"></a>putchar</h2></div></div></div><pre class="programlisting">
void
putchar(char c)
</pre><p>
Delivers a single character to the current console
device.
</p></div><div class="section" title="getchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2919239"></a>getchar</h2></div></div></div><pre class="programlisting">
char
getchar(void)
</pre><p>
Reads a single character from any of the available
console devices. The current console device is set to
that which delivered this character. This blocks until
a character is available.
</p></div><div class="section" title="flush"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2936340"></a>flush</h2></div></div></div><pre class="programlisting">
void
flush(void)
</pre><p>
Flushes the current console device output buffer. Any
pending characters will be delivered to the target device.
xo </p></div><div class="section" title="ao_add_stdio"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2919501"></a>ao_add_stdio</h2></div></div></div><pre class="programlisting">
void
ao_add_stdio(char (*pollchar)(void),
void (*putchar)(char),
void (*flush)(void))
</pre><p>
This adds another console device to the available
list.
</p><p>
'pollchar' returns either an available character or
AO_READ_AGAIN if none is available. Significantly, it does
not block. The device driver must set 'ao_stdin_ready' to
1 and call ao_wakeup(&ao_stdin_ready) when it receives
input to tell getchar that more data is available, at
which point 'pollchar' will be called again.
</p><p>
'putchar' queues a character for output, flushing if the output buffer is
full. It may block in this case.
</p><p>
'flush' forces the output buffer to be flushed. It may
block until the buffer is delivered, but it is not
required to do so.
</p></div></div><div class="chapter" title="Chapter 8. Command line interface"><div class="titlepage"><div><div><h2 class="title"><a name="id2918389"></a>Chapter 8. Command line interface</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2946883">ao_cmd_register</a></span></dt><dt><span class="section"><a href="#id2936480">ao_cmd_lex</a></span></dt><dt><span class="section"><a href="#id2934898">ao_cmd_put16</a></span></dt><dt><span class="section"><a href="#id2946243">ao_cmd_put8</a></span></dt><dt><span class="section"><a href="#id2945885">ao_cmd_white</a></span></dt><dt><span class="section"><a href="#id2934349">ao_cmd_hex</a></span></dt><dt><span class="section"><a href="#id2944178">ao_cmd_decimal</a></span></dt><dt><span class="section"><a href="#id2942940">ao_match_word</a></span></dt><dt><span class="section"><a href="#id2940080">ao_cmd_init</a></span></dt></dl></div><p>
AltOS includes a simple command line parser which is hooked up
to the stdio interfaces permitting remote control of the device
over USB or the RF link as desired. Each command uses a single
character to invoke it, the remaining characters on the line are
available as parameters to the command.
</p><div class="section" title="ao_cmd_register"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2946883"></a>ao_cmd_register</h2></div></div></div><pre class="programlisting">
void
ao_cmd_register(__code struct ao_cmds *cmds)
</pre><p>
This registers a set of commands with the command
parser. There is a fixed limit on the number of command
sets, the system will panic if too many are registered.
Each command is defined by a struct ao_cmds entry:
</p><pre class="programlisting">
struct ao_cmds {
char cmd;
void (*func)(void);
const char *help;
};
</pre><p>
'cmd' is the character naming the command. 'func' is the
function to invoke and 'help' is a string displayed by the
'?' command. Syntax errors found while executing 'func'
should be indicated by modifying the global ao_cmd_status
variable with one of the following values:
</p><div class="variablelist"><dl><dt></dt><dd><p>
The command was parsed successfully. There is no
need to assign this value, it is the default.
</p></dd><dt></dt><dd><p>
A token in the line was invalid, such as a number
containing invalid characters. The low-level
lexing functions already assign this value as needed.
</p></dd><dt></dt><dd><p>
The command line is invalid for some reason other
than invalid tokens.
</p></dd></dl></div><p>
</p></div><div class="section" title="ao_cmd_lex"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2936480"></a>ao_cmd_lex</h2></div></div></div><pre class="programlisting">
void
ao_cmd_lex(void);
</pre><p>
This gets the next character out of the command line
buffer and sticks it into ao_cmd_lex_c. At the end of the
line, ao_cmd_lex_c will get a newline ('\n') character.
</p></div><div class="section" title="ao_cmd_put16"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2934898"></a>ao_cmd_put16</h2></div></div></div><pre class="programlisting">
void
ao_cmd_put16(uint16_t v);
</pre><p>
Writes 'v' as four hexadecimal characters.
</p></div><div class="section" title="ao_cmd_put8"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2946243"></a>ao_cmd_put8</h2></div></div></div><pre class="programlisting">
void
ao_cmd_put8(uint8_t v);
</pre><p>
Writes 'v' as two hexadecimal characters.
</p></div><div class="section" title="ao_cmd_white"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2945885"></a>ao_cmd_white</h2></div></div></div><pre class="programlisting">
void
ao_cmd_white(void)
</pre><p>
This skips whitespace by calling ao_cmd_lex while
ao_cmd_lex_c is either a space or tab. It does not skip
any characters if ao_cmd_lex_c already non-white.
</p></div><div class="section" title="ao_cmd_hex"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2934349"></a>ao_cmd_hex</h2></div></div></div><pre class="programlisting">
void
ao_cmd_hex(void)
</pre><p>
This reads a 16-bit hexadecimal value from the command
line with optional leading whitespace. The resulting value
is stored in ao_cmd_lex_i;
</p></div><div class="section" title="ao_cmd_decimal"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2944178"></a>ao_cmd_decimal</h2></div></div></div><pre class="programlisting">
void
ao_cmd_decimal(void)
</pre><p>
This reads a 32-bit decimal value from the command
line with optional leading whitespace. The resulting value
is stored in ao_cmd_lex_u32 and the low 16 bits are stored
in ao_cmd_lex_i;
</p></div><div class="section" title="ao_match_word"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2942940"></a>ao_match_word</h2></div></div></div><pre class="programlisting">
uint8_t
ao_match_word(__code char *word)
</pre><p>
This checks to make sure that 'word' occurs on the command
line. It does not skip leading white space. If 'word' is
found, then 1 is returned. Otherwise, ao_cmd_status is set to
ao_cmd_syntax_error and 0 is returned.
</p></div><div class="section" title="ao_cmd_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2940080"></a>ao_cmd_init</h2></div></div></div><pre class="programlisting">
void
ao_cmd_init(void
</pre><p>
Initializes the command system, setting up the built-in
commands and adding a task to run the command processing
loop. It should be called by 'main' before ao_start_scheduler.
</p></div></div><div class="chapter" title="Chapter 9. CC1111 USB target device"><div class="titlepage"><div><div><h2 class="title"><a name="id2921413"></a>Chapter 9. CC1111 USB target device</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2938680">ao_usb_flush</a></span></dt><dt><span class="section"><a href="#id2929550">ao_usb_putchar</a></span></dt><dt><span class="section"><a href="#id2921252">ao_usb_pollchar</a></span></dt><dt><span class="section"><a href="#id2928933">ao_usb_getchar</a></span></dt><dt><span class="section"><a href="#id2945790">ao_usb_disable</a></span></dt><dt><span class="section"><a href="#id2926157">ao_usb_enable</a></span></dt><dt><span class="section"><a href="#id2929728">ao_usb_init</a></span></dt></dl></div><p>
The CC1111 contains a full-speed USB target device. It can be
programmed to offer any kind of USB target, but to simplify
interactions with a variety of operating systems, AltOS provides
only a single target device profile, that of a USB modem which
has native drivers for Linux, Windows and Mac OS X. It would be
easy to change the code to provide an alternate target device if
necessary.
</p><p>
To the rest of the system, the USB device looks like a simple
two-way byte stream. It can be hooked into the command line
interface if desired, offering control of the device over the
USB link. Alternatively, the functions can be accessed directly
to provide for USB-specific I/O.
</p><div class="section" title="ao_usb_flush"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2938680"></a>ao_usb_flush</h2></div></div></div><pre class="programlisting">
void
ao_usb_flush(void);
</pre><p>
Flushes any pending USB output. This queues an 'IN' packet
to be delivered to the USB host if there is pending data,
or if the last IN packet was full to indicate to the host
that there isn't any more pending data available.
</p></div><div class="section" title="ao_usb_putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929550"></a>ao_usb_putchar</h2></div></div></div><pre class="programlisting">
void
ao_usb_putchar(char c);
</pre><p>
If there is a pending 'IN' packet awaiting delivery to the
host, this blocks until that has been fetched. Then, this
adds a byte to the pending IN packet for delivery to the
USB host. If the USB packet is full, this queues the 'IN'
packet for delivery.
</p></div><div class="section" title="ao_usb_pollchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2921252"></a>ao_usb_pollchar</h2></div></div></div><pre class="programlisting">
char
ao_usb_pollchar(void);
</pre><p>
If there are no characters remaining in the last 'OUT'
packet received, this returns AO_READ_AGAIN. Otherwise, it
returns the next character, reporting to the host that it
is ready for more data when the last character is gone.
</p></div><div class="section" title="ao_usb_getchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2928933"></a>ao_usb_getchar</h2></div></div></div><pre class="programlisting">
char
ao_usb_getchar(void);
</pre><p>
This uses ao_pollchar to receive the next character,
blocking while ao_pollchar returns AO_READ_AGAIN.
</p></div><div class="section" title="ao_usb_disable"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2945790"></a>ao_usb_disable</h2></div></div></div><pre class="programlisting">
void
ao_usb_disable(void);
</pre><p>
This turns off the USB controller. It will no longer
respond to host requests, nor return characters. Calling
any of the i/o routines while the USB device is disabled
is undefined, and likely to break things. Disabling the
USB device when not needed saves power.
</p><p>
Note that neither TeleDongle nor TeleMetrum are able to
signal to the USB host that they have disconnected, so
after disabling the USB device, it's likely that the cable
will need to be disconnected and reconnected before it
will work again.
</p></div><div class="section" title="ao_usb_enable"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2926157"></a>ao_usb_enable</h2></div></div></div><pre class="programlisting">
void
ao_usb_enable(void);
</pre><p>
This turns the USB controller on again after it has been
disabled. See the note above about needing to physically
remove and re-insert the cable to get the host to
re-initialize the USB link.
</p></div><div class="section" title="ao_usb_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929728"></a>ao_usb_init</h2></div></div></div><pre class="programlisting">
void
ao_usb_init(void);
</pre><p>
This turns the USB controller on, adds a task to handle
the control end point and adds the usb I/O functions to
the stdio system. Call this from main before
ao_start_scheduler.
</p></div></div><div class="chapter" title="Chapter 10. CC1111 Serial peripheral"><div class="titlepage"><div><div><h2 class="title"><a name="id2940757"></a>Chapter 10. CC1111 Serial peripheral</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2935496">ao_serial_getchar</a></span></dt><dt><span class="section"><a href="#id2927850">ao_serial_putchar</a></span></dt><dt><span class="section"><a href="#id2939780">ao_serial_drain</a></span></dt><dt><span class="section"><a href="#id2935064">ao_serial_set_speed</a></span></dt><dt><span class="section"><a href="#id2910707">ao_serial_init</a></span></dt></dl></div><p>
The CC1111 provides two USART peripherals. AltOS uses one for
asynch serial data, generally to communicate with a GPS device,
and the other for a SPI bus. The UART is configured to operate
in 8-bits, no parity, 1 stop bit framing. The default
configuration has clock settings for 4800, 9600 and 57600 baud
operation. Additional speeds can be added by computing
appropriate clock values.
</p><p>
To prevent loss of data, AltOS provides receive and transmit
fifos of 32 characters each.
</p><div class="section" title="ao_serial_getchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2935496"></a>ao_serial_getchar</h2></div></div></div><pre class="programlisting">
char
ao_serial_getchar(void);
</pre><p>
Returns the next character from the receive fifo, blocking
until a character is received if the fifo is empty.
</p></div><div class="section" title="ao_serial_putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2927850"></a>ao_serial_putchar</h2></div></div></div><pre class="programlisting">
void
ao_serial_putchar(char c);
</pre><p>
Adds a character to the transmit fifo, blocking if the
fifo is full. Starts transmitting characters.
</p></div><div class="section" title="ao_serial_drain"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2939780"></a>ao_serial_drain</h2></div></div></div><pre class="programlisting">
void
ao_serial_drain(void);
</pre><p>
Blocks until the transmit fifo is empty. Used internally
when changing serial speeds.
</p></div><div class="section" title="ao_serial_set_speed"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2935064"></a>ao_serial_set_speed</h2></div></div></div><pre class="programlisting">
void
ao_serial_set_speed(uint8_t speed);
</pre><p>
Changes the serial baud rate to one of
AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or
AO_SERIAL_SPEED_57600. This first flushes the transmit
fifo using ao_serial_drain.
</p></div><div class="section" title="ao_serial_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2910707"></a>ao_serial_init</h2></div></div></div><pre class="programlisting">
void
ao_serial_init(void)
</pre><p>
Initializes the serial peripheral. Call this from 'main'
before jumping to ao_start_scheduler. The default speed
setting is AO_SERIAL_SPEED_4800.
</p></div></div><div class="chapter" title="Chapter 11. CC1111 Radio peripheral"><div class="titlepage"><div><div><h2 class="title"><a name="id2921332"></a>Chapter 11. CC1111 Radio peripheral</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id2942652">ao_radio_set_telemetry</a></span></dt><dt><span class="section"><a href="#id2932868">ao_radio_set_packet</a></span></dt><dt><span class="section"><a href="#id2924450">ao_radio_set_rdf</a></span></dt><dt><span class="section"><a href="#id2929401">ao_radio_idle</a></span></dt><dt><span class="section"><a href="#id2939945">ao_radio_get</a></span></dt><dt><span class="section"><a href="#id2945270">ao_radio_put</a></span></dt><dt><span class="section"><a href="#id2940062">ao_radio_abort</a></span></dt><dt><span class="section"><a href="#id2935488">ao_radio_send</a></span></dt><dt><span class="section"><a href="#id2933204">ao_radio_recv</a></span></dt><dt><span class="section"><a href="#id2922259">ao_radio_rdf</a></span></dt><dt><span class="section"><a href="#id2933786">ao_packet_putchar</a></span></dt><dt><span class="section"><a href="#id2901174">ao_packet_pollchar</a></span></dt><dt><span class="section"><a href="#id2923629">ao_packet_slave_start</a></span></dt><dt><span class="section"><a href="#id2924465">ao_packet_slave_stop</a></span></dt><dt><span class="section"><a href="#id2930002">ao_packet_slave_init</a></span></dt><dt><span class="section"><a href="#id2929069">ao_packet_master_init</a></span></dt></dl></div><p>
The CC1111 radio transceiver sends and receives digital packets
with forward error correction and detection. The AltOS driver is
fairly specific to the needs of the TeleMetrum and TeleDongle
devices, using it for other tasks may require customization of
the driver itself. There are three basic modes of operation:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Telemetry mode. In this mode, TeleMetrum transmits telemetry
frames at a fixed rate. The frames are of fixed size. This
is strictly a one-way communication from TeleMetrum to
TeleDongle.
</p></li><li class="listitem"><p>
Packet mode. In this mode, the radio is used to create a
reliable duplex byte stream between TeleDongle and
TeleMetrum. This is an asymmetrical protocol with
TeleMetrum only transmitting in response to a packet sent
from TeleDongle. Thus getting data from TeleMetrum to
TeleDongle requires polling. The polling rate is adaptive,
when no data has been received for a while, the rate slows
down. The packets are checked at both ends and invalid
data are ignored.
</p><p>
On the TeleMetrum side, the packet link is hooked into the
stdio mechanism, providing an alternate data path for the
command processor. It is enabled when the unit boots up in
'idle' mode.
</p><p>
On the TeleDongle side, the packet link is enabled with a
command; data from the stdio package is forwarded over the
packet link providing a connection from the USB command
stream to the remote TeleMetrum device.
</p></li><li class="listitem"><p>
Radio Direction Finding mode. In this mode, TeleMetrum
constructs a special packet that sounds like an audio tone
when received by a conventional narrow-band FM
receiver. This is designed to provide a beacon to track
the device when other location mechanisms fail.
</p></li></ol></div><p>
</p><div class="section" title="ao_radio_set_telemetry"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2942652"></a>ao_radio_set_telemetry</h2></div></div></div><pre class="programlisting">
void
ao_radio_set_telemetry(void);
</pre><p>
Configures the radio to send or receive telemetry
packets. This includes packet length, modulation scheme and
other RF parameters. It does not include the base frequency
or channel though. Those are set at the time of transmission
or reception, in case the values are changed by the user.
</p></div><div class="section" title="ao_radio_set_packet"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2932868"></a>ao_radio_set_packet</h2></div></div></div><pre class="programlisting">
void
ao_radio_set_packet(void);
</pre><p>
Configures the radio to send or receive packet data. This
includes packet length, modulation scheme and other RF
parameters. It does not include the base frequency or
channel though. Those are set at the time of transmission or
reception, in case the values are changed by the user.
</p></div><div class="section" title="ao_radio_set_rdf"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2924450"></a>ao_radio_set_rdf</h2></div></div></div><pre class="programlisting">
void
ao_radio_set_rdf(void);
</pre><p>
Configures the radio to send RDF 'packets'. An RDF 'packet'
is a sequence of hex 0x55 bytes sent at a base bit rate of
2kbps using a 5kHz deviation. All of the error correction
and data whitening logic is turned off so that the resulting
modulation is received as a 1kHz tone by a conventional 70cm
FM audio receiver.
</p></div><div class="section" title="ao_radio_idle"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929401"></a>ao_radio_idle</h2></div></div></div><pre class="programlisting">
void
ao_radio_idle(void);
</pre><p>
Sets the radio device to idle mode, waiting until it reaches
that state. This will terminate any in-progress transmit or
receive operation.
</p></div><div class="section" title="ao_radio_get"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2939945"></a>ao_radio_get</h2></div></div></div><pre class="programlisting">
void
ao_radio_get(void);
</pre><p>
Acquires the radio mutex and then configures the radio
frequency using the global radio calibration and channel
values.
</p></div><div class="section" title="ao_radio_put"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2945270"></a>ao_radio_put</h2></div></div></div><pre class="programlisting">
void
ao_radio_put(void);
</pre><p>
Releases the radio mutex.
</p></div><div class="section" title="ao_radio_abort"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2940062"></a>ao_radio_abort</h2></div></div></div><pre class="programlisting">
void
ao_radio_abort(void);
</pre><p>
Aborts any transmission or reception process by aborting the
associated DMA object and calling ao_radio_idle to terminate
the radio operation.
</p></div><p>
In telemetry mode, you can send or receive a telemetry
packet. The data from receiving a packet also includes the RSSI
and status values supplied by the receiver. These are added
after the telemetry data.
</p><div class="section" title="ao_radio_send"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2935488"></a>ao_radio_send</h2></div></div></div><pre class="programlisting">
void
ao_radio_send(__xdata struct ao_telemetry *telemetry);
</pre><p>
This sends the specific telemetry packet, waiting for the
transmission to complete. The radio must have been set to
telemetry mode. This function calls ao_radio_get() before
sending, and ao_radio_put() afterwards, to correctly
serialize access to the radio device.
</p></div><div class="section" title="ao_radio_recv"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2933204"></a>ao_radio_recv</h2></div></div></div><pre class="programlisting">
void
ao_radio_recv(__xdata struct ao_radio_recv *radio);
</pre><p>
This blocks waiting for a telemetry packet to be received.
The radio must have been set to telemetry mode. This
function calls ao_radio_get() before receiving, and
ao_radio_put() afterwards, to correctly serialize access
to the radio device. This returns non-zero if a packet was
received, or zero if the operation was aborted (from some
other task calling ao_radio_abort()).
</p></div><p>
In radio direction finding mode, there's just one function to
use
</p><div class="section" title="ao_radio_rdf"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2922259"></a>ao_radio_rdf</h2></div></div></div><pre class="programlisting">
void
ao_radio_rdf(int ms);
</pre><p>
This sends an RDF packet lasting for the specified amount
of time. The maximum length is 1020 ms.
</p></div><p>
Packet mode is asymmetrical and is configured at compile time
for either master or slave mode (but not both). The basic I/O
functions look the same at both ends, but the internals are
different, along with the initialization steps.
</p><div class="section" title="ao_packet_putchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2933786"></a>ao_packet_putchar</h2></div></div></div><pre class="programlisting">
void
ao_packet_putchar(char c);
</pre><p>
If the output queue is full, this first blocks waiting for
that data to be delivered. Then, queues a character for
packet transmission. On the master side, this will
transmit a packet if the output buffer is full. On the
slave side, any pending data will be sent the next time
the master polls for data.
</p></div><div class="section" title="ao_packet_pollchar"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2901174"></a>ao_packet_pollchar</h2></div></div></div><pre class="programlisting">
char
ao_packet_pollchar(void);
</pre><p>
This returns a pending input character if available,
otherwise returns AO_READ_AGAIN. On the master side, if
this empties the buffer, it triggers a poll for more data.
</p></div><div class="section" title="ao_packet_slave_start"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2923629"></a>ao_packet_slave_start</h2></div></div></div><pre class="programlisting">
void
ao_packet_slave_start(void);
</pre><p>
This is available only on the slave side and starts a task
to listen for packet data.
</p></div><div class="section" title="ao_packet_slave_stop"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2924465"></a>ao_packet_slave_stop</h2></div></div></div><pre class="programlisting">
void
ao_packet_slave_stop(void);
</pre><p>
Disables the packet slave task, stopping the radio receiver.
</p></div><div class="section" title="ao_packet_slave_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2930002"></a>ao_packet_slave_init</h2></div></div></div><pre class="programlisting">
void
ao_packet_slave_init(void);
</pre><p>
Adds the packet stdio functions to the stdio package so
that when packet slave mode is enabled, characters will
get send and received through the stdio functions.
</p></div><div class="section" title="ao_packet_master_init"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2929069"></a>ao_packet_master_init</h2></div></div></div><pre class="programlisting">
void
ao_packet_master_init(void);
</pre><p>
Adds the 'p' packet forward command to start packet mode.
</p></div></div></div></body></html>
|
