AN668 P RECISION 32™ S OFTWARE D EVELOPMENT K IT C ODE E XAMPLES O VERVIEW 1. Introduction The Precision32™ code examples are part of the Software Development Kit (SDK) installed with the Precision32 software package available at www.silabs.com/32bit-software. The code examples are simple and complete examples that illustrate and highlight the peripheral modes and features. They are also modular so code can be copied into an application base, making peripheral-specific code development easy. Figure 1 shows the Precision32 firmware layer block diagram. CODE EXAMPLES APPLICATION si32Library Callback RTOS CMSIS CoreSupport (from ARM) CMSIS CMSIS DeviceSupport (from Silicon Labs) HARDWARE Figure 1. Firmware Layer Block Diagram 2. Relevant Documentation Precision32 Application Notes are listed on the following website: www.silabs.com/32bit-mcu. AN664: Precision32™ CMSIS and HAL User’s Guide AN667: Getting Started with the Silicon Labs Precision32™ IDE AN670: Getting Started with the Silicon Labs Precision32™ AppBuilder AN673: Precision32™ Software Development Kit (SDK) Overview Rev. 0.1 2/12 Copyright © 2012 by Silicon Laboratories AN668 AN668 3. Code Example Organization The code examples are separated by device and are located in si32-x.y\Examples\device, where x is the major SDK version, and y is the minor SDK version. Each code example has its own folder named with the peripheral or example name. The IDE can import these code examples using the instructions in the application note, “AN667: Getting Started with the Silicon Labs Precision32 IDE”. Sub-directories under the example folder include example projects for uVision and IAR. Figure 2 displays the code example organization on disk. Figure 2. Code Example Organization 2 Rev. 0.1 AN668 4. Detailed Documentation The detailed documentation for each code example is in the Readme file in the example folders.This file includes a basic description of the example, the resources and clock speeds used, notes on the example and supported modes, and detailed how-to-use steps. The Blinky_Readme.txt file shown in Figure 3 is installed in si32-x.y\Example\sim3u1xx\Blinky for SiM3U1xx devices after installing the Precision32 software package. Figure 3. Code Example Documentation Rev. 0.1 3 AN668 5. SiM3U1xx Blinky Example Blinky uses the SiM3U1xx RTC0 module and SysTick to toggle two LEDs. PB2.10 (LED on the SiM3U1xx MCU card) toggles every 500 ms using the RTC counting 10 ms intervals. PB2.11 (also an LED) toggles every second using SysTick. The example also reads the switches on the MCU card (PB2.8 and PB2.9) every 500 ms and prints their status to the Console view (semi-hosting) by default. The code examples follow the Silicon Labs AppBuilder file generation structure: generated files are included in the src\generated folder with the g- prefix, and application files are in the src folder with my- prefix. All of the modes implemented in the example are called from main. In the Blinky example, main calls gModes_enter_my_default_mode() from gModes.c, which then calls gCpu_enter_default_config() in gCpu.c, and so forth. These code examples use the Silicon Labs Hardware Access Layer (HAL) macros by default. Figure 4. Blinky Example 4 Rev. 0.1 AN668 5.1. Blinky Application-Specific Files 5.1.1. main.c The main.c file calls functions from the gModes.c and the port HAL as shown in Figure 5. This file also includes all the main application code that sits in a while(1) loop, toggling the LED pins or reading the switches and printing their status to the Console view. Blinky main.c gModes.c si32Hal SI32_PBSTD_A_Type.c Figure 5. main.c Dependencies 5.1.2. myCpu.c This file has the application-specific implementation of mySystemInit() called by system_sim3u1xx.c in the HAL. For Blinky, this function: Disables the Watchdog Timer. Enables APB to the Port Bank modules. Sets the Serial Wire Viewer pin (PB1.3) to push-pull. Figure 6 shows the dependencies for myCpu.c. Blinky myCpu.c si32Hal SI32_CLKCTRL_A_Type.c system_sim3u1xx.c SI32_WDTIMER_A_Type.c SI32_PBSTD_A_Type.c Figure 6. myCpu.c Dependencies 5.1.3. myPB.c This file doesn’t include any application-specific code for the Blinky example. Rev. 0.1 5 AN668 5.1.4. myRtc0.c The myRtc0.c file includes the second-level handlers for the RTC0 Alarm 0 and RTC0 oscillator fail interrupts. These second-level handlers are called from the first-level handlers in gRtc0.c. The second-level Alarm 0 handler: Reads the RTC0 counter value. Sets the RTC0 Alarm 0 value with a new value equal to the current counter value + 10 ms. Increments msTicks_10, which keeps track of the 10 ms intervals. Clears the Alarm 0 interrupt in the RTC0 module. The second-level oscillator fail handler sits in a while(1) loop to indicate an unrecoverable error condition. Figure 6 shows the dependencies for myRtc0.c. Blinky myRtc.c gRtc.c si32Hal SI32_RTC_A_Type.c SI32_RTC_A_Type.c SI32_RTC_A_Type.c Figure 7. myRtc0.c Dependencies 5.2. Blinky AppBuilder-Generated Files 5.2.1. gCpu.c This file contains the SysTick handler, which increments the msTicks variable, and the gCpu_enter_default_config() function, which is called from gModes_enter_my_default_mode() in gModes.c. This function sets the SystemCoreClock variable to 20 MHz, since Blinky uses the Low Power Oscillator, and sets the SysTick timer to trigger every millisecond. Figure 8 shows the dependencies for gCpu.c. Blinky gCpu.c gModes.c si32Hal core_cm3.h Figure 8. gCpu.c Dependencies 6 Rev. 0.1 AN668 5.2.2. gModes.c The gModes.c file has two functions: gModes_enter_my_default_mode() and gModes_enter_my_off_mode(). The default mode function places the device in the default mode after a reset and gCpu_enter_default_config() from gCpu.c, gPB_enter_default_config() from gPB.c, gRtc0_enter_default_config() from gRtc0.c. calls and The off mode function is not currently called from anywhere in the project and includes calls to gRtc0_enter_off_config() from gRtc0.c and gPB_enter_off_config() from gPB.c. Figure 9 illustrates the dependencies diagram for gModes.c. Blinky gCpu.c gModes.c gPB.c gRtc0.c si32Hal Figure 9. gModes.c Dependencies Rev. 0.1 7 AN668 5.2.3. gPB.c This file includes two functions: gPB_enter_off_config() and gPB_enter_default_config(). The gPB_enter_off_config() function is called by gModes_enter_my_off_mode() in gModes.c and sets all the pins to digital input mode, disables crossbar 1, and disables the APB clock to the port registers. The gPB_enter_default_config() function: Enables the APB clock to the port registers. Sets the SWV pin to push-pull. Enables crossbar 1. Sets the PB2.10 and PB2.11 pins to push-pull. Sets the PB2.8 and PB2.9 pins to digital input mode. Configures the PB0.9 and PB0.10 RTC0 oscillator input pins as analog inputs. Configures PB2.7 to output the RTC0 clock by setting PB2.7 to push-pull, skipping the PB2.0-PB2.6 pins on crossbar 1, and enabling the oscillator output on crossbar 1. Figure 10 shows the dependencies for gPB.c. Blinky gPB.c si32Hal SI32_CLKCTRL_A_Type.c SI32_PBSTD_A_Type.c SI32_PBCFG_A_Type.c Figure 10. gPB.c Dependencies 8 Rev. 0.1 AN668 5.2.4. gRtc0.c The gRtc0.c file includes the first-level interrupt handlers for the RTC0 oscillator fail (RTC0FAIL_IRQHandler()) and Alarm 0 (RTC0ALRM_IRQHandler()). These first-level interrupt handlers just call the second-level handlers and must use the handler names defined in sim3u1xx.h, the device-specific header file. In addition to the first-level interrupt handlers, gRtc0.c has two functions: gRtc_enter_off_config() and gRtc0_enter_default_config(). The gRtc_enter_off_config() function disables the Alarm 0 interrupt in the RTC0 module, clears any pending oscillator fail or Alarm 0 interrupts in the NVIC, and disables these two interrupts in the NVIC. In addition, the function stops the RTC0 timer, disables the RTC0 module, and disables the APB clock to RTC0. The gRtc0_enter_default_config() function: Enables the APB clock to the RTC0 module. the RTC module and configures it for crystal oscillator mode. Sets the initial Alarm 0 value for 10 ms. Clears any pending interrupts and enables the interrupts in the NVIC. Enables the Alarm 0 interrupt in the RTC0 module. Enables the RTC0 output. Figure 11 shows the dependencies for gRtc0.c. Enables Blinky gRtc0.c myRtc0.c si32Hal SI32_CLKCTRL_A_Type.c SI32_RTC_A_Type.c core_cm3.h Figure 11. gRtc0.c Dependencies Rev. 0.1 9 AN668 CONTACT INFORMATION Silicon Laboratories Inc. 400 West Cesar Chavez Austin, TX 78701 Tel: 1+(512) 416-8500 Fax: 1+(512) 416-9669 Toll Free: 1+(877) 444-3032 Please visit the Silicon Labs Technical Support web page: https://www.silabs.com/support/pages/contacttechnicalsupport.aspx and register to submit a technical support request. The information in this document is believed to be accurate in all respects at the time of publication but is subject to change without notice. Silicon Laboratories assumes no responsibility for errors and omissions, and disclaims responsibility for any consequences resulting from the use of information included herein. Additionally, Silicon Laboratories assumes no responsibility for the functioning of undescribed features or parameters. Silicon Laboratories reserves the right to make changes without further notice. Silicon Laboratories makes no warranty, representation or guarantee regarding the suitability of its products for any particular purpose, nor does Silicon Laboratories assume any liability arising out of the application or use of any product or circuit, and specifically disclaims any and all liability, including without limitation consequential or incidental damages. Silicon Laboratories products are not designed, intended, or authorized for use in applications intended to support or sustain life, or for any other application in which the failure of the Silicon Laboratories product could create a situation where personal injury or death may occur. Should Buyer purchase or use Silicon Laboratories products for any such unintended or unauthorized application, Buyer shall indemnify and hold Silicon Laboratories harmless against all claims and damages. Silicon Laboratories and Silicon Labs are trademarks of Silicon Laboratories Inc. Other products or brandnames mentioned herein are trademarks or registered trademarks of their respective holders. 10 Rev. 0.1