Copyright © 2010 Keith Packard
+
Copyright © 2010 Keith Packard
This document is released under the terms of the Creative Commons ShareAlike 3.0 license. -
| Revision History | |
|---|---|
| Revision 1.1 | 05 November 2012 |
| Portable version | |
| Revision 0.1 | 22 November 2010 |
| Initial content | |
Table of Contents
| Revision History | |
|---|---|
| Revision 1.1 | 05 November 2012 |
| Portable version | |
| Revision 0.1 | 22 November 2010 |
| Initial content | |
Table of Contents
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. -
Table of Contents
+
Table of Contents
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. -
+
These primitive operations provide the abstraction needed to run the multi-tasking framework while providing reliable interrupt delivery. -
+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. -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. -These functions provide an abstract interface to configure and manipulate GPIO pins. -
+
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. -
+#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. -
#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.
-
These macros read and write individual GPIO pins. -
+#define ao_gpio_set(port, bit, pin, value)Sets the specified port/bit or pin to the indicated value -
Table of Contents
+
Table of Contents
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. -
+
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. -
+
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. -
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. -
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. -
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. -
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. -
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. -
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. -
+
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. -
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. -
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. -
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. -
Table of Contents
+
Table of Contents
This chapter documents how to create, destroy and schedule AltOS tasks. -
+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. -void ao_sleep(__xdata void *wchan)@@ -348,7 +348,7 @@ ao_sleep(&ao_radio_done); ao_arch_release_interrupts();
-
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. -
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. -void ao_start_scheduler(void);This is called from 'main' when the system is all initialized and ready to run. It will not return. -
Table of Contents
+
Table of Contents
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. -
+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. -
void ao_delay(uint16_t ticks);Suspend the current task for at least 'ticks' clock units. -
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. -
Table of Contents
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. -
+void ao_mutex_get(__xdata uint8_t *mutex);Acquires the specified mutex, blocking if the mutex is owned by another task. -
Table of Contents
The CC1111 and STM32L both contain a useful bit of extra hardware in the form of a number of programmable DMA engines. They can be configured to copy data in memory, or @@ -476,7 +476,7 @@ 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. -
+uint8_t ao_dma_alloc(__xdata uint8_t *done)@@ -486,7 +486,7 @@ 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. -
void ao_dma_set_transfer(uint8_t id, void __xdata *srcaddr, @@ -500,24 +500,24 @@ cfg1 are values directly out of the CC1111 documentation and tell the DMA engine what the transfer unit size, direction and step are. -void ao_dma_start(uint8_t id);Arm the specified DMA engine and await a signal from either hardware or software to start transferring data. -
void ao_dma_trigger(uint8_t id)Trigger the specified DMA engine to start copying data. -
uint8_t ao_dma_done[]; void @@ -525,7 +525,7 @@Reserve a DMA engine for exclusive use by one driver. -
void ao_dma_set_transfer(uint8_t id, void *peripheral, @@ -538,7 +538,7 @@ value directly out of the STM32L documentation and tells the DMA engine what the transfer unit size, direction and step are. -void ao_dma_set_isr(uint8_t index, void (*isr)(int))@@ -546,7 +546,7 @@ completes in lieu of setting the ao_dma_done bits. Use this when some work needs to be done when the DMA finishes that cannot wait until user space resumes. -
void ao_dma_start(uint8_t id);@@ -557,33 +557,33 @@ 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. -
void ao_dma_done_transfer(uint8_t id);Signals that a specific DMA engine is done being used. This allows multiple drivers to use the same DMA engine safely. -
Table of Contents
AltOS offers a stdio interface over USB, serial and the RF - packet link. This provides for control of the device localy or + packet link. This provides for control of the device locally or remotely. This is hooked up to the stdio functions by providing the standard putchar/getchar/flush functions. These automatically multiplex the available communication channels; output is always delivered to the channel which provided the most recent input. -
+char getchar(void)@@ -591,13 +591,13 @@ console devices. The current console device is set to that which delivered this character. This blocks until a character is available. -
void flush(void)Flushes the current console device output buffer. Any pending characters will be delivered to the target device. - xo
Table of Contents
+
Table of Contents
AltOS includes a simple command line parser which is hooked up to the stdio interfaces permitting remote control of the device over USB, serial 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. -
+void ao_cmd_register(__code struct ao_cmds *cmds)@@ -656,38 +656,38 @@ The command line is invalid for some reason other than invalid tokens.
-
void
ao_cmd_lex(void);
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. -
void
ao_cmd_white(void)
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. -
void
ao_cmd_hex(void)
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; -
void
ao_cmd_decimal(void)
@@ -695,7 +695,7 @@ 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; -
uint8_t
ao_match_word(__code char *word)
@@ -703,14 +703,14 @@ 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. -
Table of Contents
+
Table of Contents
AltOS contains a full-speed USB target device driver. It can be programmed to offer any kind of USB target, but to simplify interactions with a variety of operating systems, AltOS provides @@ -724,7 +724,7 @@ 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. -
+void ao_usb_flush(void);@@ -732,7 +732,7 @@ 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. -
void ao_usb_putchar(char c);@@ -741,7 +741,7 @@ 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. -
char ao_usb_pollchar(void);@@ -749,13 +749,13 @@ 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. -
char ao_usb_getchar(void);This uses ao_pollchar to receive the next character, blocking while ao_pollchar returns AO_READ_AGAIN. -
void ao_usb_disable(void);@@ -770,7 +770,7 @@ after disabling the USB device, it's likely that the cable will need to be disconnected and reconnected before it will work again. -
void ao_usb_enable(void);@@ -778,7 +778,7 @@ 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. -
Table of Contents
+
Table of Contents
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 @@ -797,25 +797,25 @@
To prevent loss of data, AltOS provides receive and transmit fifos of 32 characters each. -
+char ao_serial_getchar(void);Returns the next character from the receive fifo, blocking until a character is received if the fifo is empty. -
void ao_serial_putchar(char c);Adds a character to the transmit fifo, blocking if the fifo is full. Starts transmitting characters. -
void ao_serial_drain(void);Blocks until the transmit fifo is empty. Used internally when changing serial speeds. -
void ao_serial_set_speed(uint8_t speed);@@ -823,14 +823,14 @@ AO_SERIAL_SPEED_4800, AO_SERIAL_SPEED_9600 or AO_SERIAL_SPEED_57600. This first flushes the transmit fifo using ao_serial_drain. -
Table of Contents
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 @@ -868,7 +868,7 @@ receiver. This is designed to provide a beacon to track the device when other location mechanisms fail.
-
void ao_radio_set_telemetry(void);
@@ -877,7 +877,7 @@ 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. -
void ao_radio_set_packet(void);
@@ -886,7 +886,7 @@ 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. -
void ao_radio_set_rdf(void);
@@ -896,38 +896,38 @@ 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. -
void ao_radio_idle(void);
Sets the radio device to idle mode, waiting until it reaches that state. This will terminate any in-progress transmit or receive operation. -
void ao_radio_get(void);
Acquires the radio mutex and then configures the radio frequency using the global radio calibration and channel values. -
void ao_radio_abort(void);
Aborts any transmission or reception process by aborting the associated DMA object and calling ao_radio_idle to terminate the radio operation. -
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. -
+void ao_radio_send(__xdata struct ao_telemetry *telemetry);@@ -936,7 +936,7 @@ telemetry mode. This function calls ao_radio_get() before sending, and ao_radio_put() afterwards, to correctly serialize access to the radio device. -
In radio direction finding mode, there's just one function to use -
+
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. -
+void ao_packet_putchar(char c);@@ -971,32 +971,32 @@ 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. -
char ao_packet_pollchar(void);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. -
void ao_packet_slave_start(void);This is available only on the slave side and starts a task to listen for packet data. -
void ao_packet_slave_stop(void);Disables the packet slave task, stopping the radio receiver. -
void ao_packet_slave_init(void);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. -