AltOS

1.1. ao_arch_block_interrupts/ao_arch_release_interrupts
1.2. ao_arch_save_regs, ao_arch_save_stack, - ao_arch_restore_stack
1.3. ao_arch_wait_interupt

3. Programming the 8051 with SDCC

2.1. GPIO setup
2.2. Reading and writing GPIO pins

1. 8051 memory spaces

1.1. __data
1.2. __idata
1.3. __xdata
1.4. __pdata
1.5. __code
1.6. __bit
1.7. __sfr, __sfr16, __sfr32, __sbit

2. Function calls on the 8051

2.1. __reentrant functions
2.2. Non __reentrant functions
2.3. __interrupt functions
2.4. __critical functions and statements

4. Task functions

1. ao_add_task
2. ao_exit
3. ao_sleep
4. ao_wakeup
5. ao_alarm
6. ao_start_scheduler
7. ao_clock_init

5. Timer Functions

1. ao_time
2. ao_delay
3. ao_timer_set_adc_interval
4. ao_timer_init

6. AltOS Mutexes

1. ao_mutex_get
2. ao_mutex_put

7. DMA engine

1.1. ao_dma_alloc
1.2. ao_dma_set_transfer
1.3. ao_dma_start
1.4. ao_dma_trigger
1.5. ao_dma_abort

9. Command line interface

2.1. ao_dma_alloc
2.2. ao_dma_set_transfer
2.3. ao_dma_set_isr
2.4. ao_dma_start
2.5. ao_dma_done_transfer
2.6. ao_dma_abort

8. Stdio interface

1. putchar
2. getchar
3. flush
4. ao_add_stdio

1. ao_cmd_register
2. ao_cmd_lex
3. ao_cmd_put16
4. ao_cmd_put8
5. ao_cmd_white
6. ao_cmd_hex
7. ao_cmd_decimal
8. ao_match_word
9. ao_cmd_init

10. USB target device

1. ao_usb_flush
2. ao_usb_putchar
3. ao_usb_pollchar
4. ao_usb_getchar
5. ao_usb_disable
6. ao_usb_enable
7. ao_usb_init

11. Serial peripherals

1. ao_serial_getchar
2. ao_serial_putchar
3. ao_serial_drain
4. ao_serial_set_speed
5. ao_serial_init

12. CC1111 Radio peripheral

1. Radio Introduction

2. ao_radio_set_telemetry

3. ao_radio_set_packet

4. ao_radio_set_rdf

5. ao_radio_idle

6. ao_radio_get

7. ao_radio_put

8. ao_radio_abort

9. Radio Telemetry

9.1. ao_radio_send
9.2. ao_radio_recv

10. Radio Direction Finding

10.1. ao_radio_rdf

11. Radio Packet Mode

11.1. ao_packet_putchar
11.2. ao_packet_pollchar
11.3. ao_packet_slave_start
11.4. ao_packet_slave_stop
11.5. ao_packet_slave_init
11.6. ao_packet_master_init

Chapter 1. Overview

Revision History
Revision 1.1	05 November 2012
Portable version
Revision 0.1	22 November 2010
Initial content

Table of Contents

1. Overview

2. AltOS Porting Layer

1.1. ao_arch_block_interrupts/ao_arch_release_interrupts
1.2. ao_arch_save_regs, ao_arch_save_stack, + ao_arch_restore_stack
1.3. ao_arch_wait_interupt

3. Programming the 8051 with SDCC

2.1. GPIO setup
2.2. Reading and writing GPIO pins

1. 8051 memory spaces

1.1. __data
1.2. __idata
1.3. __xdata
1.4. __pdata
1.5. __code
1.6. __bit
1.7. __sfr, __sfr16, __sfr32, __sbit

2. Function calls on the 8051

2.1. __reentrant functions
2.2. Non __reentrant functions
2.3. __interrupt functions
2.4. __critical functions and statements

4. Task functions

1. ao_add_task
2. ao_exit
3. ao_sleep
4. ao_wakeup
5. ao_alarm
6. ao_start_scheduler
7. ao_clock_init

5. Timer Functions

1. ao_time
2. ao_delay
3. ao_timer_set_adc_interval
4. ao_timer_init

6. AltOS Mutexes

1. ao_mutex_get
2. ao_mutex_put

7. DMA engine

1.1. ao_dma_alloc
1.2. ao_dma_set_transfer
1.3. ao_dma_start
1.4. ao_dma_trigger
1.5. ao_dma_abort

9. Command line interface

2.1. ao_dma_alloc
2.2. ao_dma_set_transfer
2.3. ao_dma_set_isr
2.4. ao_dma_start
2.5. ao_dma_done_transfer
2.6. ao_dma_abort

8. Stdio interface

1. putchar
2. getchar
3. flush
4. ao_add_stdio

1. ao_cmd_register
2. ao_cmd_lex
3. ao_cmd_put16
4. ao_cmd_put8
5. ao_cmd_white
6. ao_cmd_hex
7. ao_cmd_decimal
8. ao_match_word
9. ao_cmd_init

10. USB target device

1. ao_usb_flush
2. ao_usb_putchar
3. ao_usb_pollchar
4. ao_usb_getchar
5. ao_usb_disable
6. ao_usb_enable
7. ao_usb_init

11. Serial peripherals

1. ao_serial_getchar
2. ao_serial_putchar
3. ao_serial_drain
4. ao_serial_set_speed
5. ao_serial_init

12. CC1111 Radio peripheral

1. Radio Introduction

2. ao_radio_set_telemetry

3. ao_radio_set_packet

4. ao_radio_set_rdf

5. ao_radio_idle

6. ao_radio_get

7. ao_radio_put

8. ao_radio_abort

9. Radio Telemetry

9.1. ao_radio_send
9.2. ao_radio_recv

10. Radio Direction Finding

10.1. ao_radio_rdf

11. Radio Packet Mode

11.1. ao_packet_putchar
11.2. ao_packet_pollchar
11.3. ao_packet_slave_start
11.4. ao_packet_slave_stop
11.5. ao_packet_slave_init
11.6. ao_packet_master_init

Chapter 1. Overview

AltOS is a operating system built for a variety of microcontrollers used in Altus Metrum devices. It has a simple porting layer for each CPU while providing a convenient @@ -85,8 +85,8 @@

As you can see, a long sequence of subsystems are initialized and then the scheduler is started. -

Chapter 2. AltOS Porting Layer

Table of Contents

1.1. ao_arch_block_interrupts/ao_arch_release_interrupts
1.2. ao_arch_save_regs, ao_arch_save_stack, - ao_arch_restore_stack
1.3. ao_arch_wait_interupt

2.1. GPIO setup
2.2. Reading and writing GPIO pins

Chapter 2. AltOS Porting Layer

Table of Contents

1.1. ao_arch_block_interrupts/ao_arch_release_interrupts
1.2. ao_arch_save_regs, ao_arch_save_stack, + ao_arch_restore_stack
1.3. ao_arch_wait_interupt

1. 8051 memory spaces

2.1. GPIO setup
2.2. Reading and writing GPIO pins

AltOS provides a CPU-independent interface to various common microcontroller subsystems, including GPIO pins, interrupts, SPI, I2C, USB and asynchronous serial interfaces. By making @@ -94,11 +94,11 @@ application code can all be written that work on any supported CPU. Many of the architecture abstraction interfaces are prefixed with ao_arch. -

1. Low-level CPU operations

These primitive operations provide the abstraction needed to run the multi-tasking framework while providing reliable interrupt delivery. -

1.1. ao_arch_block_interrupts/ao_arch_release_interrupts

+      
1.1. ao_arch_block_interrupts/ao_arch_release_interrupts
 	  static inline void
 	  ao_arch_block_interrupts(void);
 	  
@@ -109,7 +109,7 @@
 	  discard any interrupts. Use these for sections of code that
 	  must be atomic with respect to any code run from an
 	  interrupt handler.
-	
1.2. ao_arch_save_regs, ao_arch_save_stack,
+	
1.2. ao_arch_save_regs, ao_arch_save_stack,
 	ao_arch_restore_stack
 	  static inline void
 	  ao_arch_save_regs(void);
@@ -127,7 +127,7 @@
 	  in the current ao_task structure. ao_arch_restore_stack
 	  switches back to the saved stack, restores all registers and
 	  branches to the saved return address.
-	
1.3. ao_arch_wait_interupt
+	
1.3. ao_arch_wait_interupt
 	  #define ao_arch_wait_interrupt()
 	

 	  This stops the CPU, leaving clocks and interrupts
@@ -139,10 +139,10 @@
 	  disable interrupts again. If the CPU doesn't have any
 	  reduced power mode, this must at the least allow pending
 	  interrupts to be processed.
-	
2. GPIO operations

+	
2. GPIO operations

 	These functions provide an abstract interface to configure and
 	manipulate GPIO pins.
-      
2.1. GPIO setup

+      
2.1. GPIO setup

 	  These macros may be invoked at system initialization time to
 	  configure pins as needed for system operation. One tricky
 	  aspect is that some chips provide direct access to specific
@@ -151,14 +151,14 @@
 	  provide both port+bit and pin arguments. Simply define the
 	  arguments needed for the target platform and leave the
 	  others undefined.
-	
2.1.1. ao_enable_output
+	
2.1.1. ao_enable_output
 	    #define ao_enable_output(port, bit, pin, value)
 	  

 	    Set the specified port+bit (also called 'pin') for output,
 	    initializing to the specified value. The macro must avoid
 	    driving the pin with the opposite value if at all
 	    possible.
-	  
2.1.2. ao_enable_input
+	  
2.1.2. ao_enable_input
 	    #define ao_enable_input(port, bit, mode)
 	  

 	    Sets the specified port/bit to be an input pin. 'mode' is
@@ -176,18 +176,18 @@
 		0. Don't apply either a pull-up or pull-down. A
 		disconnected pin will read an undetermined value.
 

-	  
2.2. Reading and writing GPIO pins

+	  
2.2. Reading and writing GPIO pins

 	  These macros read and write individual GPIO pins.
-	
2.2.1. ao_gpio_set
+	
2.2.1. ao_gpio_set
 	    #define ao_gpio_set(port, bit, pin, value)
 	  

 	    Sets the specified port/bit or pin to the indicated value
-	  
2.2.2. ao_gpio_get
+	  
2.2.2. ao_gpio_get
 	    #define ao_gpio_get(port, bit, pin)
 	  

 	    Returns either 1 or 0 depending on whether the input to
 	    the pin is high or low.
-	  
Chapter 3. Programming the 8051 with SDCC
Table of Contents
1. 8051 memory spaces
1.1. __data
1.2. __idata
1.3. __xdata
1.4. __pdata
1.5. __code
1.6. __bit
1.7. __sfr, __sfr16, __sfr32, __sbit
2. Function calls on the 8051
2.1. __reentrant functions
2.2. Non __reentrant functions
2.3. __interrupt functions
2.4. __critical functions and statements

+

Chapter 3. Programming the 8051 with SDCC

Table of Contents

1.1. __data
1.2. __idata
1.3. __xdata
1.4. __pdata
1.5. __code
1.6. __bit
1.7. __sfr, __sfr16, __sfr32, __sbit

2. Function calls on the 8051

2.1. __reentrant functions
2.2. Non __reentrant functions
2.3. __interrupt functions
2.4. __critical functions and statements

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 @@ -198,7 +198,7 @@

When built on other architectures, the various SDCC-specific symbols are #defined as empty strings so they don't affect the compiler. -

1. 8051 memory spaces

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 @@ -212,7 +212,7 @@ is decorated with a memory space identifier which clutters the code but makes the resulting code far smaller and more efficient. -

1.1. __data

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 @@ -222,42 +222,42 @@ these registers located at 0x00 - 0x1F. AltOS uses only the first bank at 0x00 - 0x07, leaving the other 24 bytes available for other data. -

1.2. __idata

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. -

1.3. __xdata

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. -

1.4. __pdata

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. -

1.5. __code

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. -

1.6. __bit

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. -

1.7. sfr, sfr16, sfr32, sbit

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. -

2. Function calls on the 8051

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 @@ -265,7 +265,7 @@ non-reentrant, and also consume space for parameters and locals even when they are not running. The benefit is smaller code and faster execution. -

2.1. __reentrant functions

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 @@ -278,7 +278,7 @@ invoked can also be marked as __reentrant. The resulting code will be larger, but the savings in memory are frequently worthwhile. -

2.2. Non __reentrant functions

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 @@ -290,14 +290,14 @@ non-reentrant. Because of this, interrupt handlers must not invoke any library functions, including the multiply and divide code. -

2.3. __interrupt functions

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. -

2.4. __critical functions and statements

SDCC has built-in support for suspending interrupts during critical code. Functions marked as __critical will have interrupts suspended for the whole period of @@ -308,9 +308,9 @@ quickly as possible. AltOS doesn't use this form in shared code as other compilers wouldn't know what to do. Use ao_arch_block_interrupts and ao_arch_release_interrupts instead. -

Chapter 4. Task functions

Table of Contents

1. ao_add_task
2. ao_exit
3. ao_sleep
4. ao_wakeup
5. ao_alarm
6. ao_start_scheduler
7. ao_clock_init

Chapter 4. Task functions

Table of Contents

1. ao_add_task
2. ao_exit
3. ao_sleep
4. ao_wakeup
5. ao_alarm
6. ao_start_scheduler
7. ao_clock_init

This chapter documents how to create, destroy and schedule AltOS tasks. -

1. ao_add_task

+    
1. ao_add_task
 	void
 	ao_add_task(__xdata struct ao_task * task,
 	            void (*start)(void),
@@ -321,12 +321,12 @@
 	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.
-      
2. ao_exit
+      
2. ao_exit
 	void
 	ao_exit(void)
       

 	This terminates the current task.
-      
3. ao_sleep
+      
3. ao_sleep
 	void
 	ao_sleep(__xdata void *wchan)
       

@@ -348,7 +348,7 @@
 	          ao_sleep(&ao_radio_done);
 	  ao_arch_release_interrupts();

4. ao_wakeup

 	void
 	ao_wakeup(__xdata void *wchan)

@@ -365,7 +365,7 @@ Note that this need not block interrupts 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. -

5. ao_alarm

 	void
 	ao_alarm(uint16_t delay);
 
@@ -390,18 +390,18 @@
 	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.
-

6. ao_start_scheduler

 	void
 	ao_start_scheduler(void);

This is called from 'main' when the system is all initialized and ready to run. It will not return. -

7. ao_clock_init

 	void
 	ao_clock_init(void);

This initializes the main CPU clock and switches to it. -

Chapter 5. Timer Functions

Table of Contents

1. ao_time
2. ao_delay
3. ao_timer_set_adc_interval
4. ao_timer_init

Chapter 5. Timer Functions

Table of Contents

1. ao_time
2. ao_delay
3. ao_timer_set_adc_interval
4. ao_timer_init

AltOS sets up one of the CPU 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 @@ -409,51 +409,51 @@ collect current data readings. Doing this from the ISR ensures that the values are sampled at a regular rate, independent of any scheduling jitter. -

1. ao_time

 	uint16_t
 	ao_time(void)

Returns the current system tick count. Note that this is only a 16 bit value, and so it wraps every 655.36 seconds. -

2. ao_delay

 	void
 	ao_delay(uint16_t ticks);

Suspend the current task for at least 'ticks' clock units. -

3. ao_timer_set_adc_interval

 	void
 	ao_timer_set_adc_interval(uint8_t interval);

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. -

4. ao_timer_init

 	void
 	ao_timer_init(void)

This turns on the 100Hz tick. It is required for any of the time-based functions to work. It should be called by 'main' before ao_start_scheduler. -

Chapter 6. AltOS Mutexes

Table of Contents

1. ao_mutex_get
2. ao_mutex_put

Chapter 6. AltOS Mutexes

Table of Contents

1. ao_mutex_get
2. ao_mutex_put

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. -

1. ao_mutex_get

 	void
 	ao_mutex_get(__xdata uint8_t *mutex);

Acquires the specified mutex, blocking if the mutex is owned by another task. -

2. ao_mutex_put

 	void
 	ao_mutex_put(__xdata uint8_t *mutex);

Releases the specified mutex, waking up all tasks waiting for it. -

Chapter 7. DMA engine

Table of Contents

1.1. ao_dma_alloc
1.2. ao_dma_set_transfer
1.3. ao_dma_start
1.4. ao_dma_trigger
1.5. ao_dma_abort

2.1. ao_dma_alloc
2.2. ao_dma_set_transfer
2.3. ao_dma_set_isr
2.4. ao_dma_start
2.5. ao_dma_done_transfer
2.6. ao_dma_abort

Chapter 7. DMA engine

Table of Contents

1.1. ao_dma_alloc
1.2. ao_dma_set_transfer
1.3. ao_dma_start
1.4. ao_dma_trigger
1.5. ao_dma_abort