X-Git-Url: https://git.gag.com/?p=fw%2Faltos;a=blobdiff_plain;f=doc%2Faltos.xsl;h=37bb58da0440dae3122f89845f4fad80fa7e14e0;hp=9a88a5b562d9cc79e858b8f3c882d3b49bd28b03;hb=da42f406e88ccc821cd45d5a94d5afec65ec50e9;hpb=737f2fdd012202f453120ece117ae5e859b32082 diff --git a/doc/altos.xsl b/doc/altos.xsl index 9a88a5b5..37bb58da 100644 --- a/doc/altos.xsl +++ b/doc/altos.xsl @@ -1,6 +1,6 @@ +"/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd"> AltOS @@ -37,41 +37,41 @@ 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: - - - 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. - - - - 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. - - - - Sleep/wakeup scheduling. Taken directly from ancient - Unix designs, these two provide the fundemental scheduling - primitive within AltOS. - - - - Mutexes. As a locking primitive, mutexes are easier to - use than semaphores, at least in my experience. - - - - Timers. Tasks can set an alarm which will abort any - pending sleep, allowing operations to time-out instead of - blocking forever. - - - + + + 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. + + + + 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. + + + + Sleep/wakeup scheduling. Taken directly from ancient + Unix designs, these two provide the fundemental scheduling + primitive within AltOS. + + + + Mutexes. As a locking primitive, mutexes are easier to + use than semaphores, at least in my experience. + + + + Timers. Tasks can set an alarm which will abort any + pending sleep, allowing operations to time-out instead of + blocking forever. + + + The device drivers and other subsystems in AltOS are @@ -82,28 +82,28 @@ may add tasks to the scheduler to handle the device. A typical main program, thus, looks like: -void -main(void) -{ - ao_clock_init(); + 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(); -} + /* 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(); + } As you can see, a long sequence of subsystems are initialized and then the scheduler is started. @@ -137,96 +137,79 @@ main(void) code but makes the resulting code far smaller and more efficient. - - SDCC 8051 memory spaces - - __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 - 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. - - - - - __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. - - - - - __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. - - - - - __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. - - - - - __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. - - - - - __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. - - - - - __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. - - - - +
+ __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 + 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. + +
+
+ __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. + +
+
+ __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. + +
+
+ __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. + +
+
+ __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. + +
+
+ __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. + +
+
+ __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. + +
Function calls on the 8051 @@ -305,124 +288,128 @@ main(void) This chapter documents how to create, destroy and schedule AltOS tasks. - - AltOS Task Functions - - ao_add_task - - -void -ao_add_task(__xdata struct ao_task * task, - void (*start)(void), - __code char *name); - - - 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. - - - - - ao_exit - - -void -ao_exit(void) - - - This terminates the current task. - - - - - ao_sleep - - -void -ao_sleep(__xdata void *wchan) - - - 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. - - - - - ao_wakeup - - -void -ao_wakeup(__xdata void *wchan) - - - Wake all tasks blocked on 'wchan'. This makes them - available to be run again, but does not actually switch - to another task. - - - - - ao_alarm - - -void -ao_alarm(uint16_t delay) - - - 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. - - - - - ao_wake_task - - -void -ao_wake_task(__xdata struct ao_task *task) - - - Force a specific task to wake up, independent of which - 'wchan' it is waiting for. - - - - - 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. - - - - - ao_clock_init - - -void -ao_clock_init(void) - - - 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. - - - - +
+ ao_add_task + + void + ao_add_task(__xdata struct ao_task * task, + void (*start)(void), + __code char *name); + + + 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. + +
+
+ ao_exit + + void + ao_exit(void) + + + This terminates the current task. + +
+
+ ao_sleep + + void + ao_sleep(__xdata void *wchan) + + + 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. + + + 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: + + __critical while (!ao_radio_done) + ao_sleep(&ao_radio_done); + + +
+
+ ao_wakeup + + void + ao_wakeup(__xdata void *wchan) + + + 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: + + if (RFIF & RFIF_IM_DONE) { + ao_radio_done = 1; + ao_wakeup(&ao_radio_done); + RFIF &= ~RFIF_IM_DONE; + } + + 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. + +
+
+ ao_alarm + + void + ao_alarm(uint16_t delay) + + + 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. + + ao_alarm(ao_packet_master_delay); + __critical while (!ao_radio_dma_done) + if (ao_sleep(&ao_radio_dma_done) != 0) + ao_radio_abort(); + + 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. + +
+
+ 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. + +
+
+ ao_clock_init + + void + ao_clock_init(void) + + + 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. + +
Timer Functions @@ -435,62 +422,51 @@ ao_clock_init(void) that the ADC values are sampled at a regular rate, independent of any scheduling jitter. - - AltOS Timer Functions - - 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. - - - - - ao_delay - - -void -ao_delay(uint16_t ticks); - - - Suspend the current task for at least 'ticks' clock units. - - - - - 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. - - - - - ao_timer_init - - -void -ao_timer_init(void) - - - 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. - - - - +
+ 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. + +
+
+ ao_delay + + void + ao_delay(uint16_t ticks); + + + Suspend the current task for at least 'ticks' clock units. + +
+
+ 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. + +
+
+ ao_timer_init + + void + ao_timer_init(void) + + + 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. + +
AltOS Mutexes @@ -502,35 +478,28 @@ ao_timer_init(void) already held by the current task or releasing a mutex not held by the current task will both cause a panic. - - Mutex Functions - - ao_mutex_get - - -void -ao_mutex_get(__xdata uint8_t *mutex); - - - Acquires the specified mutex, blocking if the mutex is - owned by another task. - - - - - ao_mutex_put - - -void -ao_mutex_put(__xdata uint8_t *mutex); - - - Releases the specified mutex, waking up all tasks waiting - for it. - - - - +
+ ao_mutex_get + + void + ao_mutex_get(__xdata uint8_t *mutex); + + + Acquires the specified mutex, blocking if the mutex is + owned by another task. + +
+
+ ao_mutex_put + + void + ao_mutex_put(__xdata uint8_t *mutex); + + + Releases the specified mutex, waking up all tasks waiting + for it. + +
CC1111 DMA engine @@ -554,86 +523,73 @@ ao_mutex_put(__xdata uint8_t *mutex); hardware device. When copying data from memory to hardware, the transfer is usually initiated by software. - - AltOS DMA functions - - ao_dma_alloc - - -uint8_t -ao_dma_alloc(__xdata uint8_t *done) - - - 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. - - - - - ao_dma_set_transfer - - -void -ao_dma_set_transfer(uint8_t id, - void __xdata *srcaddr, - void __xdata *dstaddr, - uint16_t count, - uint8_t cfg0, - uint8_t cfg1) - - - 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. - - - - - ao_dma_start - - -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. - - - - - ao_dma_trigger - - -void -ao_dma_trigger(uint8_t id) - - - Trigger the specified DMA engine to start copying data. - - - - - ao_dma_abort - - -void -ao_dma_abort(uint8_t id) - - - Terminate any in-progress DMA transation, marking its - 'done' variable with the AO_DMA_ABORTED bit. - - - - +
+ ao_dma_alloc + + uint8_t + ao_dma_alloc(__xdata uint8_t *done) + + + 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. + +
+
+ ao_dma_set_transfer + + void + ao_dma_set_transfer(uint8_t id, + void __xdata *srcaddr, + void __xdata *dstaddr, + uint16_t count, + uint8_t cfg0, + uint8_t cfg1) + + + 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. + +
+
+ ao_dma_start + + 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. + +
+
+ ao_dma_trigger + + void + ao_dma_trigger(uint8_t id) + + + Trigger the specified DMA engine to start copying data. + +
+
+ ao_dma_abort + + void + ao_dma_abort(uint8_t id) + + + Terminate any in-progress DMA transation, marking its + 'done' variable with the AO_DMA_ABORTED bit. + +
SDCC Stdio interface @@ -646,83 +602,72 @@ ao_dma_abort(uint8_t id) channels; output is always delivered to the channel which provided the most recent input. - - SDCC stdio functions - - putchar - - -void -putchar(char c) - - - Delivers a single character to the current console - device. - - - - - getchar - - -char -getchar(void) - - - 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. - - - - - flush - - -void -flush(void) - - - Flushes the current console device output buffer. Any - pending characters will be delivered to the target device. -xo - - - - ao_add_stdio - - -void -ao_add_stdio(char (*pollchar)(void), - void (*putchar)(char), - void (*flush)(void)) - - - This adds another console device to the available - list. - - - '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. - - - 'putchar' queues a character for output, flushing if the output buffer is - full. It may block in this case. - - - 'flush' forces the output buffer to be flushed. It may - block until the buffer is delivered, but it is not - required to do so. - - - - - +
+ putchar + + void + putchar(char c) + + + Delivers a single character to the current console + device. + +
+
+ getchar + + char + getchar(void) + + + 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. + +
+
+ flush + + void + flush(void) + + + Flushes the current console device output buffer. Any + pending characters will be delivered to the target device. + xo +
+
+ ao_add_stdio + + void + ao_add_stdio(char (*pollchar)(void), + void (*putchar)(char), + void (*flush)(void)) + + + This adds another console device to the available + list. + + + '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. + + + 'putchar' queues a character for output, flushing if the output buffer is + full. It may block in this case. + + + 'flush' forces the output buffer to be flushed. It may + block until the buffer is delivered, but it is not + required to do so. + +
+ Command line interface @@ -732,176 +677,155 @@ ao_add_stdio(char (*pollchar)(void), character to invoke it, the remaining characters on the line are available as parameters to the command. - - AltOS command line parsing functions - - ao_cmd_register - - -void -ao_cmd_register(__code struct ao_cmds *cmds) - - - 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: - -struct ao_cmds { - char cmd; - void (*func)(void); - const char *help; -}; - - '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: - - - ao_cmd_success - - - The command was parsed successfully. There is no - need to assign this value, it is the default. - - - - - ao_cmd_lex_error - - - 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. - - - - - ao_syntax_error - - - The command line is invalid for some reason other - than invalid tokens. - - - - - - - - - ao_cmd_lex - - -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. - - - - - ao_cmd_put16 - - -void -ao_cmd_put16(uint16_t v); - - - Writes 'v' as four hexadecimal characters. - - - - - ao_cmd_put8 - - -void -ao_cmd_put8(uint8_t v); - - - Writes 'v' as two hexadecimal characters. - - - - - ao_cmd_white - - -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. - - - - - ao_cmd_hex - - -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; - - - - - ao_cmd_decimal - - -void -ao_cmd_decimal(void) - - - 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; - - - - - ao_match_word - - -uint8_t -ao_match_word(__code char *word) - - - 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. - - - - - ao_cmd_init - - -void -ao_cmd_init(void - - - 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. - - - - +
+ ao_cmd_register + + void + ao_cmd_register(__code struct ao_cmds *cmds) + + + 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: + + struct ao_cmds { + char cmd; + void (*func)(void); + const char *help; + }; + + '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: + + + ao_cmd_success + + + The command was parsed successfully. There is no + need to assign this value, it is the default. + + + + + ao_cmd_lex_error + + + 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. + + + + + ao_syntax_error + + + The command line is invalid for some reason other + than invalid tokens. + + + + + +
+
+ ao_cmd_lex + + 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. + +
+
+ ao_cmd_put16 + + void + ao_cmd_put16(uint16_t v); + + + Writes 'v' as four hexadecimal characters. + +
+
+ ao_cmd_put8 + + void + ao_cmd_put8(uint8_t v); + + + Writes 'v' as two hexadecimal characters. + +
+
+ ao_cmd_white + + 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. + +
+
+ ao_cmd_hex + + 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; + +
+
+ ao_cmd_decimal + + void + ao_cmd_decimal(void) + + + 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; + +
+
+ ao_match_word + + uint8_t + ao_match_word(__code char *word) + + + 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. + +
+
+ ao_cmd_init + + void + ao_cmd_init(void + + + 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. + +
CC1111 USB target device @@ -921,121 +845,104 @@ ao_cmd_init(void USB link. Alternatively, the functions can be accessed directly to provide for USB-specific I/O. - - AltOS USB functions - - ao_usb_flush - - -void -ao_usb_flush(void); - - - 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. - - - - - ao_usb_putchar - - -void -ao_usb_putchar(char c); - - - 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. - - - - - ao_usb_pollchar - - -char -ao_usb_pollchar(void); - - - 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. - - - - - ao_usb_getchar - - -char -ao_usb_getchar(void); - - - This uses ao_pollchar to receive the next character, - blocking while ao_pollchar returns AO_READ_AGAIN. - - - - - ao_usb_disable - - -void -ao_usb_disable(void); - - - 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. - - - 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. - - - - - ao_usb_enable - - -void -ao_usb_enable(void); - - - 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. - - - - - ao_usb_init - - -void -ao_usb_init(void); - - - 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. - - - - +
+ ao_usb_flush + + void + ao_usb_flush(void); + + + 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. + +
+
+ ao_usb_putchar + + void + ao_usb_putchar(char c); + + + 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. + +
+
+ ao_usb_pollchar + + char + ao_usb_pollchar(void); + + + 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. + +
+
+ ao_usb_getchar + + char + ao_usb_getchar(void); + + + This uses ao_pollchar to receive the next character, + blocking while ao_pollchar returns AO_READ_AGAIN. + +
+
+ ao_usb_disable + + void + ao_usb_disable(void); + + + 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. + + + 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. + +
+
+ ao_usb_enable + + void + ao_usb_enable(void); + + + 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. + +
+
+ ao_usb_init + + void + ao_usb_init(void); + + + 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. + +
CC1111 Serial peripheral @@ -1052,77 +959,64 @@ ao_usb_init(void); To prevent loss of data, AltOS provides receive and transmit fifos of 32 characters each. - - AltOS serial functions - - ao_serial_getchar - - -char -ao_serial_getchar(void); - - - Returns the next character from the receive fifo, blocking - until a character is received if the fifo is empty. - - - - - ao_serial_putchar - - -void -ao_serial_putchar(char c); - - - Adds a character to the transmit fifo, blocking if the - fifo is full. Starts transmitting characters. - - - - - ao_serial_drain - - -void -ao_serial_drain(void); - - - Blocks until the transmit fifo is empty. Used internally - when changing serial speeds. - - - - - ao_serial_set_speed - - -void -ao_serial_set_speed(uint8_t speed); - - - 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. - - - - - ao_serial_init - - -void -ao_serial_init(void) - - - Initializes the serial peripheral. Call this from 'main' - before jumping to ao_start_scheduler. The default speed - setting is AO_SERIAL_SPEED_4800. - - - - +
+ ao_serial_getchar + + char + ao_serial_getchar(void); + + + Returns the next character from the receive fifo, blocking + until a character is received if the fifo is empty. + +
+
+ ao_serial_putchar + + void + ao_serial_putchar(char c); + + + Adds a character to the transmit fifo, blocking if the + fifo is full. Starts transmitting characters. + +
+
+ ao_serial_drain + + void + ao_serial_drain(void); + + + Blocks until the transmit fifo is empty. Used internally + when changing serial speeds. + +
+
+ ao_serial_set_speed + + void + ao_serial_set_speed(uint8_t speed); + + + 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. + +
+
+ ao_serial_init + + void + ao_serial_init(void) + + + Initializes the serial peripheral. Call this from 'main' + before jumping to ao_start_scheduler. The default speed + setting is AO_SERIAL_SPEED_4800. + +
CC1111 Radio peripheral @@ -1177,265 +1071,221 @@ ao_serial_init(void) - - AltOS radio functions - - ao_radio_set_telemetry - - -void -ao_radio_set_telemetry(void); - - - 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. - - - - - ao_radio_set_packet - - -void -ao_radio_set_packet(void); - - - 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. - - - - - ao_radio_set_rdf - - -void -ao_radio_set_rdf(void); - - - 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. - - - - - ao_radio_idle - - -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. - - - - - ao_radio_get - - -void -ao_radio_get(void); - - - Acquires the radio mutex and then configures the radio - frequency using the global radio calibration and channel - values. - - - - - ao_radio_put - - -void -ao_radio_put(void); - - - Releases the radio mutex. - - - - - ao_radio_abort - - -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. - - - - - - AltOS radio telemetry functions - - 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. - - - ao_radio_send - - -void -ao_radio_send(__xdata struct ao_telemetry *telemetry); - - - 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. - - - - - ao_radio_recv - - -void -ao_radio_recv(__xdata struct ao_radio_recv *radio); - - - 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()). - - - - - - AltOS radio direction finding function - - In radio direction finding mode, there's just one function to - use - - - ao_radio_rdf - - -void -ao_radio_rdf(int ms); - - - This sends an RDF packet lasting for the specified amount - of time. The maximum length is 1020 ms. - - - - - - Packet mode functions - - 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. - - - ao_packet_putchar - - -void -ao_packet_putchar(char c); - - - 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. - - - - - ao_packet_pollchar - - -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. - - - - - ao_packet_slave_start - - -void -ao_packet_slave_start(void); - - - This is available only on the slave side and starts a task - to listen for packet data. - - - - - ao_packet_slave_stop - - -void -ao_packet_slave_stop(void); - - - Disables the packet slave task, stopping the radio receiver. - - - - - ao_packet_slave_init - - -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. - - - - - ao_packet_master_init - - -void -ao_packet_master_init(void); - - - Adds the 'p' packet forward command to start packet mode. - - - - +
+ ao_radio_set_telemetry + + void + ao_radio_set_telemetry(void); + + + 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. + +
+
+ ao_radio_set_packet + + void + ao_radio_set_packet(void); + + + 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. + +
+
+ ao_radio_set_rdf + + void + ao_radio_set_rdf(void); + + + 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. + +
+
+ ao_radio_idle + + 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. + +
+
+ ao_radio_get + + void + ao_radio_get(void); + + + Acquires the radio mutex and then configures the radio + frequency using the global radio calibration and channel + values. + +
+
+ ao_radio_put + + void + ao_radio_put(void); + + + Releases the radio mutex. + +
+
+ ao_radio_abort + + 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. + +
+ ao_radio_send + + void + ao_radio_send(__xdata struct ao_telemetry *telemetry); + + + 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. + +
+
+ ao_radio_recv + + void + ao_radio_recv(__xdata struct ao_radio_recv *radio); + + + 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()). + +
+ + In radio direction finding mode, there's just one function to + use + +
+ ao_radio_rdf + + void + ao_radio_rdf(int ms); + + + This sends an RDF packet lasting for the specified amount + of time. The maximum length is 1020 ms. + +
+ + 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. + +
+ ao_packet_putchar + + void + ao_packet_putchar(char c); + + + 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. + +
+
+ ao_packet_pollchar + + 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. + +
+
+ ao_packet_slave_start + + void + ao_packet_slave_start(void); + + + This is available only on the slave side and starts a task + to listen for packet data. + +
+
+ ao_packet_slave_stop + + void + ao_packet_slave_stop(void); + + + Disables the packet slave task, stopping the radio receiver. + +
+
+ ao_packet_slave_init + + 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. + +
+
+ ao_packet_master_init + + void + ao_packet_master_init(void); + + + Adds the 'p' packet forward command to start packet mode. + +