+ <chapter>
+ <title>AltOS Porting Layer</title>
+ <para>
+ AltOS provides a CPU-independent interface to various common
+ microcontroller subsystems, including GPIO pins, interrupts,
+ SPI, I2C, USB and asynchronous serial interfaces. By making
+ these CPU-independent, device drivers, generic OS and
+ application code can all be written that work on any supported
+ CPU. Many of the architecture abstraction interfaces are
+ prefixed with ao_arch.
+ </para>
+ <section>
+ <title>Low-level CPU operations</title>
+ <para>
+ These primitive operations provide the abstraction needed to
+ run the multi-tasking framework while providing reliable
+ interrupt delivery.
+ </para>
+ <section>
+ <title>ao_arch_block_interrupts/ao_arch_release_interrupts</title>
+ <programlisting>
+ static inline void
+ ao_arch_block_interrupts(void);
+
+ static inline void
+ ao_arch_release_interrupts(void);
+ </programlisting>
+ <para>
+ These disable/enable interrupt delivery, they may not
+ discard any interrupts. Use these for sections of code that
+ must be atomic with respect to any code run from an
+ interrupt handler.
+ </para>
+ </section>
+ <section>
+ <title>ao_arch_save_regs, ao_arch_save_stack,
+ ao_arch_restore_stack</title>
+ <programlisting>
+ static inline void
+ ao_arch_save_regs(void);
+
+ static inline void
+ ao_arch_save_stack(void);
+
+ static inline void
+ ao_arch_restore_stack(void);
+ </programlisting>
+ <para>
+ These provide all of the support needed to switch between
+ tasks.. ao_arch_save_regs must save all CPU registers to the
+ current stack, including the interrupt enable
+ state. ao_arch_save_stack records the current stack location
+ 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.
+ </para>
+ </section>
+ <section>
+ <title>ao_arch_wait_interupt</title>
+ <programlisting>
+ #define ao_arch_wait_interrupt()
+ </programlisting>
+ <para>
+ This stops the CPU, leaving clocks and interrupts
+ enabled. When an interrupt is received, this must wake up
+ and handle the interrupt. ao_arch_wait_interrupt is entered
+ with interrupts disabled to ensure that there is no gap
+ between determining that no task wants to run and idling the
+ CPU. It must sleep the CPU, process interrupts and then
+ disable interrupts again. If the CPU doesn't have any
+ reduced power mode, this must at the least allow pending
+ interrupts to be processed.
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>GPIO operations</title>
+ <para>
+ These functions provide an abstract interface to configure and
+ manipulate GPIO pins.
+ </para>
+ <section>
+ <title>GPIO setup</title>
+ <para>
+ 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
+ GPIO pins while others only provide access to a whole
+ register full of pins. To support this, the GPIO macros
+ provide both port+bit and pin arguments. Simply define the
+ arguments needed for the target platform and leave the
+ others undefined.
+ </para>
+ <section>
+ <title>ao_enable_output</title>
+ <programlisting>
+ #define ao_enable_output(port, bit, pin, value)
+ </programlisting>
+ <para>
+ 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.
+ </para>
+ </section>
+ <section>
+ <title>ao_enable_input</title>
+ <programlisting>
+ #define ao_enable_input(port, bit, mode)
+ </programlisting>
+ <para>
+ Sets the specified port/bit to be an input pin. 'mode' is
+ a combination of one or more of the following. Note that
+ some platforms may not support the desired mode. In that
+ case, the value will not be defined so that the program
+ will fail to compile.
+ <itemizedlist>
+ <listitem>
+<para>
+ AO_EXTI_MODE_PULL_UP. Apply a pull-up to the pin; a
+ disconnected pin will read as 1.
+</para>
+ </listitem>
+ <listitem>
+<para>
+ AO_EXTI_MODE_PULL_DOWN. Apply a pull-down to the pin;
+ a disconnected pin will read as 0.
+</para>
+ </listitem>
+ <listitem>
+<para>
+ 0. Don't apply either a pull-up or pull-down. A
+ disconnected pin will read an undetermined value.
+</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ </section>
+ <section>
+ <title>Reading and writing GPIO pins</title>
+ <para>
+ These macros read and write individual GPIO pins.
+ </para>
+ <section>
+ <title>ao_gpio_set</title>
+ <programlisting>
+ #define ao_gpio_set(port, bit, pin, value)
+ </programlisting>
+ <para>
+ Sets the specified port/bit or pin to the indicated value
+ </para>
+ </section>
+ <section>
+ <title>ao_gpio_get</title>
+ <programlisting>
+ #define ao_gpio_get(port, bit, pin)
+ </programlisting>
+ <para>
+ Returns either 1 or 0 depending on whether the input to
+ the pin is high or low.
+ </para>
+ </section>
+ </section>
+ </section>
+ </chapter>