New Contiki port to STM32W108.

cpu/stm32w108/hal/micro/cortexm3/micro-common.h

@@ -0,0 +1,271 @@
+/** @file hal/micro/cortexm3/micro-common.h
+ * @brief Utility and convenience functions for STM32W108 microcontroller,
+ *        common to both the full and minimal hal.
+ * See @ref micro for documentation.
+ *
+ * <!--(C) COPYRIGHT 2010 STMicroelectronics. All rights reserved.        -->
+ */
+
+/** @addtogroup micro
+ * See also hal/micro/cortexm3/micro.h for source code.
+ *@{
+ */
+
+#ifndef __STM32W108XX_MICRO_COMMON_H__
+#define __STM32W108XX_MICRO_COMMON_H__
+
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+#ifndef __STSTATUS_TYPE__
+#define __STSTATUS_TYPE__
+  //This is necessary here because halSleepForQsWithOptions returns an
+  //StStatus and not adding this typedef to this file breaks a
+  //whole lot of builds.
+  typedef int8u StStatus;
+#endif //__STSTATUS_TYPE__
+#endif // DOXYGEN_SHOULD_SKIP_THIS
+
+/**
+ * @brief Some registers and variables require indentifying GPIO by
+ * a single number instead of the port and pin.  This macro converts
+ * Port A pins into a single number.
+ */
+#define PORTA_PIN(y) ((0<<3)|y)
+/**
+ * @brief Some registers and variables require indentifying GPIO by
+ * a single number instead of the port and pin.  This macro converts
+ * Port B pins into a single number.
+ */
+#define PORTB_PIN(y) ((1<<3)|y)
+/**
+ * @brief Some registers and variables require indentifying GPIO by
+ * a single number instead of the port and pin.  This macro converts
+ * Port C pins into a single number.
+ */
+#define PORTC_PIN(y) ((2<<3)|y)
+
+/**
+ * @brief Resets the watchdog timer.  This function is pointed
+ * to by the macro ::halResetWatchdog(). 
+ * @warning Be very careful when using this as you can easily get into an 
+ * infinite loop.
+ */
+void halInternalResetWatchDog( void );
+
+
+/**
+ * @brief Configure an IO pin's operating mode
+ *
+ * @param io  The io pin to use, can be specified with the convenience macros
+ *            PORTA_PIN(), PORTB_PIN(), PORTC_PIN()
+ * @param config   The configuration mode to use.
+ *
+ */
+void halGpioConfig(int32u io, int32u config);
+
+
+/**
+ * @brief Calibrates the internal SlowRC to generate a 1024 Hz (1kHz) clock.
+ */
+void halInternalCalibrateSlowRc( void );
+
+/**
+ * @brief Calibrates the internal FastRC to generate a 12Mhz clock.
+ */
+void halInternalCalibrateFastRc(void);
+
+
+/**
+ * @brief Sets the trim values for the 1.8V and 1.2V regulators based upon
+ * manufacturing configuration.
+ *
+ * @param boostMode  Alter the regulator trim based upon the state
+ * of boost mode.  TRUE if boost mode is active, FALSE otherwise.
+ */
+void halInternalSetRegTrim(boolean boostMode);
+
+/** @brief Takes a slow ADC measurement of VDD_PADS in millivolts.  Due to
+ * the conversions performed, this function takes slightly under 3.2ms with a
+ * variation across successive conversions approximately +/-2mv of the average
+ * conversion.
+ *
+ * @return A slow measurement of VDD_PADS in millivolts.
+ */
+int16u stMeasureVddSlow(void);
+
+
+/** @brief Takes a fast ADC measurement of VDD_PADS in millivolts.
+ * Due to the conversions performed, this function takes slightly under 150us
+ * with a variation across successive conversions approximately +/-20mv of
+ * the average conversion.
+ *
+ * @return A fast measurement of VDD_PADS in millivolts.
+ */
+int16u stMeasureVddFast(void);
+
+
+/**
+ * @brief Calibrates the GPIO pads.  This function is called from within
+ * the stack and HAL at appropriate times.
+ */
+void halCommonCalibratePads(void);
+
+/**
+ * @brief This function is intended to be called periodically, from the
+ * stack and application, to check the XTAL bias trim is within
+ * appropriate levels and adjust if not.  This function is *not* designed
+ * to be used before halInternalSwitchToXtal() has been called.
+ */
+void halCommonCheckXtalBiasTrim(void);
+
+/**
+ * @brief Switches to running off of the 24MHz crystal, including changing
+ * the CPU to be 24MHz (FCLK sourced from SYSCLK).  The switch function
+ * will respect the BIASTRIM HI and LO flags and adjust bias trim until
+ * appropriate crystal biasing is used.  This function is called from
+ * within the stack and HAL at appropriate times.
+ */
+void halInternalSwitchToXtal(void);
+
+/**
+ * @brief Search for optimal 24MHz crystal bias trim, assuming no valid
+ * prior value.  This function is typically called during initialization
+ * of the microcontroller.
+ */
+void halInternalSearchForBiasTrim(void);
+
+/** @brief Blocks the current thread of execution for the specified
+ * amount of time, in milliseconds.
+ *
+ * The function is implemented with cycle-counted busy loops
+ * and is intended to create the short delays required when interfacing with
+ * hardware peripherals.  This function works by simply adding another
+ * layer on top of halCommonDelayMicroseconds().
+ *
+ * @param ms  The specified time, in milliseconds. 
+ */
+void halCommonDelayMilliseconds(int16u ms);
+
+
+/** @brief Puts the microcontroller to sleep in a specified mode, allows
+ * the GPIO wake sources to be determined at runtime.  This function 
+ * requires the GPIO wake sources to be defined at compile time in the board
+ * file.
+ *
+ * @note This routine always enables interrupts.
+ *
+ * @param sleepMode  A microcontroller sleep mode.
+ *
+ * @param gpioWakeBitMask  A bit mask of the GPIO that are allowed to wake
+ * the chip from deep sleep.  A high bit in the mask will enable waking
+ * the chip if the corresponding GPIO changes state.  bit0 is PA0, bit1 is
+ * PA1, bit8 is PB0, bit16 is PCO, bit23 is PC7, bits[31:24] are ignored.
+ * 
+ * @sa ::SleepModes
+ */
+void halSleepWithOptions(SleepModes sleepMode, int32u gpioWakeBitMask);
+
+
+/**
+ * @brief Uses the system timer to enter ::SLEEPMODE_WAKETIMER for
+ * approximately the specified amount of time (provided in quarter seconds),
+ * the GPIO wake sources can be provided at runtime.
+ *
+ * This function returns ::ST_SUCCESS and the duration parameter is
+ * decremented to 0 after sleeping for the specified amount of time.  If an
+ * interrupt occurs that brings the chip out of sleep, the function returns
+ * ::ST_SLEEP_INTERRUPTED and the duration parameter reports the amount of
+ * time remaining out of the original request.
+ *
+ * @note This routine always enables interrupts.
+ *
+ * @note The maximum sleep time of the hardware is limited on STM32W108 platforms
+ * to 48.5 days.  Any sleep duration greater than this limit will wake up
+ * briefly (e.g. 16 microseconds) to reenable another sleep cycle.
+ *
+ * @nostackusage
+ *
+ * @param duration The amount of time, expressed in quarter seconds, that the
+ * micro should be placed into ::SLEEPMODE_WAKETIMER.  When the function returns,
+ * this parameter provides the amount of time remaining out of the original
+ * sleep time request (normally the return value will be 0).
+ * 
+ * @param gpioWakeBitMask  A bit mask of the GPIO that are allowed to wake
+ * the chip from deep sleep.  A high bit in the mask will enable waking
+ * the chip if the corresponding GPIO changes state.  bit0 is PA0, bit1 is
+ * PA1, bit8 is PB0, bit16 is PCO, bit23 is PC7, bits[31:24] are ignored.
+ * 
+ * @return An StStatus value indicating the success or
+ *  failure of the command.
+ */
+StStatus halSleepForQsWithOptions(int32u *duration, int32u gpioWakeBitMask);
+
+/**
+ * @brief Provides access to assembly code which triggers idle sleep.
+ */
+void halInternalIdleSleep(void);
+
+/** @brief Puts the microcontroller to sleep in a specified mode.  This
+ *  internal function performs the actual sleep operation.  This function
+ *  assumes all of the wake source registers are configured properly.
+ *
+ * @note This routine always enables interrupts.
+ *
+ * @param sleepMode  A microcontroller sleep mode
+ */
+void halInternalSleep(SleepModes sleepMode);
+
+
+/**
+ * @brief Obtains the events that caused the last wake from sleep.  The
+ * meaning of each bit is as follows:
+ * - [31] = WakeInfoValid
+ * - [30] = SleepSkipped
+ * - [29] = CSYSPWRUPREQ
+ * - [28] = CDBGPWRUPREQ
+ * - [27] = PWRUP_WAKECORE
+ * - [26] = PWRUP_SLEEPTMRWRAP
+ * - [25] = PWRUP_SLEEPTMRCOMPB
+ * - [24] = PWRUP_SLEEPTMRCOMPA
+ * - [23:0] = corresponding GPIO activity
+ *  
+ * WakeInfoValid means that ::halSleepWithOptions (::halInternalSleep) has been called
+ * at least once.  Since the power on state clears the wake event info,
+ * this bit says the sleep code has been called since power on.
+ *
+ * SleepSkipped means that the chip never left the running state.  Sleep can
+ * be skipped if any wake event occurs between going ::ATOMIC and transferring
+ * control from the CPU to the power management state machine.  Sleep can
+ * also be skipped if the debugger is connected (JTAG/SerialWire CSYSPWRUPREQ
+ * signal is set).  The net affect of skipping sleep is the Low Voltage
+ * domain never goes through a power/reset cycle.
+ *
+ * @return The events that caused the last wake from sleep. 
+ */
+int32u halGetWakeInfo(void);
+
+
+/** @brief Seeds the ::halCommonGetRandom() pseudorandom number
+ * generator.
+ *
+ * It should be called by the application during initialization with a seed
+ * from the radio randon number generator.
+ *
+ * @param seed  A seed for the pseudorandom number generator.
+ */
+void halCommonSeedRandom(int32u seed);
+
+/** @brief Runs a standard LFSR to generate pseudorandom numbers.
+ *
+ * Called by the MAC in the stack to choose random backoff slots.
+ *
+ * Complicated implementations may improve the MAC's
+ * ability to avoid collisions in large networks, but it is \b critical to
+ * implement this function to return quickly.
+ */
+int16u halCommonGetRandom(void);
+
+#endif //__STM32W108XX_MICRO_COMMON_H__
+
+/**@} // END micro group
+ */
+