TI RTOS 2.00 User's Guide (Rev. F) User Spruhd4f

TI_RTOS_User_Guide_spruhd4f

User Manual: Pdf

Open the PDF directly: View PDF PDF.
Page Count: 122 [warning: Documents this large are best viewed by clicking the View PDF Link!]

TI-RTOS 2.00
User’s Guide
Literature Number: SPRUHD4F
April 2014
SPRUHD4F—April 2014 Contents 2
Submit Documentation Feedback
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1 About TI-RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.1 What is TI-RTOS? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2 What are the TI-RTOS Components?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3 SYS/BIOS — The TI-RTOS Kernel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4 UIA — TI-RTOS Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.5 NDK — TI-RTOS Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.6 IPC — TI-RTOS Interprocessor Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.7 FatFS Module in SYS/BIOS — TI-RTOS File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.8 TI-RTOS Drivers and Board Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.8.1 Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.8.2 MWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1.8.3 MSP430Ware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.8.4 TivaWare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.9 XDCtools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2 Instrumentation with TI-RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.2 Adding Logging to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.3 Modifying an Example to Upload Logging Data at Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.3.1 Project Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.3.2 Code Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.3.3 Configuration Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.4 Using Log Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.4.1 Adding Log Events to your Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.4.2 Using Instrumented or Non-Instrumented Libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.5 Viewing the Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.5.1 Using RTOS Analyzer and System Analyzer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.5.2 Viewing Log Records in ROV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
3 Debugging TI-RTOS Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.1 Using CCS Debugging Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.2 Generating printf Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2.1 Output with printf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2.2 Output with System_printf() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.3 Controlling Software Versions for Use with TI-RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3.4 Understanding the Build Flow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4 Board-Specific Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.2 Board-Specific Code Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.3 Linker Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4 Target Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3Contents SPRUHD4F—April 2014
Submit Documentation Feedback
Contents www.ti.com
5 TI-RTOS Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.2 Driver Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.2.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.2.2 Driver Object Declarations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
5.2.3 Dynamic Configuration and Common APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.2.4 TI-RTOS Driver Implementations for Concerto Devices . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.2.5 TI-RTOS Driver Implementations for TivaC Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.2.6 TI-RTOS Driver Hwis for MSP430 Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
5.3 EMAC Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.3.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.3.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.3.3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.3.4 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.3.5 Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.3.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.4 UART Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.4.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.4.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.4.3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.4.4 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.4.5 Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.4.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.5 I2C Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.5.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.5.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.5.3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.5.4 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.5.5 I2C Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.5.6 I2C Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.5.7 Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.5.8 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.6 GPIO Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.6.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.6.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.6.3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.6.4 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
5.6.5 Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.6.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.7 SPI Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.7.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.7.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.7.3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.7.4 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.7.5 Callback and Blocking Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.7.6 SPI Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.7.7 Master/Slave Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.7.8 Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.7.9 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
4Contents SPRUHD4F—April 2014
Submit Documentation Feedback
Contents www.ti.com
5.8 SPIMessageQTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.8.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.8.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.8.3 Error Conditions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.8.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5.9 SDSPI Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.9.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.9.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.9.3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.9.4 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.9.5 Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5.9.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5.10 USBMSCHFatFs Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5.10.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5.10.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5.10.3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.10.4 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.10.5 Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
5.10.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
5.11 USB Reference Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
5.11.1 USB Reference Modules in TI-RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
5.11.2 USB Reference Module Design Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.12 USB Device and Host Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5.13 Watchdog Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.13.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.13.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
5.13.3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
5.13.4 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
5.13.5 Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
5.13.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
5.14 WiFi Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
5.14.1 Static Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
5.14.2 Runtime Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.14.3 APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.14.4 Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
5.14.5 Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
5.14.6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
6 TI-RTOS Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.2 SysFlex Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.3 UARTMon Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.3.1 UARTMon with CCS Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
6.3.2 GUI Composer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
6.4 UART Example Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
7 Using the FatFs File System Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.1 Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.2 FatFs, SYS/BIOS, and TI-RTOS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
7.3 Using FatFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.3.1 Static FatFS Module Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
SPRUHD4F—April 2014 Contents 5
Submit Documentation Feedback
www.ti.com Contents
7.3.2 Defining Drive Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.3.3 Preparing FatFs Drivers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
7.3.4 Opening Files Using FatFs APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.3.5 Opening Files Using C I/O APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.4 Cautionary Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
8 Rebuilding TI-RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8.1 Rebuilding TI-RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8.1.1 Building TI-RTOS for CCS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
8.1.2 Building TI-RTOS for IAR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.1.3 Building TI-RTOS for GCC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
8.2 Rebuilding MSP430Ware's driverlib for TI-RTOS and Its Drivers. . . . . . . . . . . . . . . . . . . . . . . . . 103
8.3 Rebuilding Individual Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
9 Memory Usage with TI-RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
9.1 Memory Footprint Reduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
9.2 Networking Stack Memory Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
A Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
SPRUHD4F—April 2014 Read This First 6
Submit Documentation Feedback
Preface
SPRUHD4F—April 2014
Read This First
About This Manual
This manual describes TI-RTOS and contains information related to all supported device families. The
version number as of the publication of this manual is v2.00.
Notational Conventions
This document uses the following conventions:
•
Program listings, program examples, and interactive displays are shown in a special typeface.
Examples use a bold version of the special typeface for emphasis.
Here is a sample program listing:
•
Square brackets ( [ and ] ) identify an optional parameter. If you use an optional parameter, you
specify the information within the brackets. Unless the square brackets are in a bold typeface, do not
enter the brackets themselves.
Trademarks
Registered trademarks of Texas Instruments include Stellaris and StellarisWare. Trademarks of Texas
Instruments include: the Texas Instruments logo, Texas Instruments, TI, TI.COM, C2000, C5000, C6000,
Code Composer, Code Composer Studio, Concerto, controlSUITE, DSP/BIOS, MSP430, MSP430Ware,
SPOX, Sitara, TI-RTOS, Tiva, TivaWare, TMS320, TMS320C5000, TMS320C6000, and TMS320C2000.
ARM is a registered trademark, and Cortex is a trademark of ARM Limited.
Windows is a registered trademark of Microsoft Corporation.
Linux is a registered trademark of Linus Torvalds.
IAR Systems and IAR Embedded Workbench are registered trademarks of IAR Systems AB:
All other brand or product names are trademarks or registered trademarks of their respective companies
or organizations.
April 13, 2014
#include <xdc/runtime/System.h>
int main(void){
System_printf("Hello World!\n");
return (0);
}
SPRUHD4F—April 2014 About TI-RTOS 7
Submit Documentation Feedback
Chapter 1
SPRUHD4F—April 2014
About TI-RTOS
This chapter provides an overview of TI-RTOS.
1.1 What is TI-RTOS?
TI-RTOS is a scalable, one-stop embedded tools ecosystem for TI devices. It
scales from a real-time multitasking kernel (SYS/BIOS) to a complete RTOS
solution including additional middleware components and device drivers. By
providing essential system software components that are pre-tested and
preintegrated, TI-RTOS enables you to focus on differentiating your application.
If you use Code Composer Studio (CCS), you can install TI-RTOS in the CCS
App Center. There are several different versions of TI-RTOS to support
different device families, including TI-RTOS for MSP430, TI-RTOS for TivaC,
and TI-RTOS for C2000. You can also use TI-RTOS outside of CCS, including
with IAR Embedded Workbench and GNU compilers.
For information about installing TI-RTOS and creating and configuring examples that use TI-RTOS, see
the TI-RTOS Getting Started Guide for your device family:
•
TI-RTOS for C6000 Getting Started Guide -- SPRUHU2
•
TI-RTOS for C2000 Getting Started Guide -- SPRUHU3
•
TI-RTOS for MSP430 Getting Started Guide -- SPRUHU4
•
TI-RTOS for TivaC Getting Started Guide -- SPRUHU5
•
TI-RTOS for Sitara Getting Started Guide -- SPRUHU6
1.1 What is TI-RTOS? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.2 What are the TI-RTOS Components? . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3 SYS/BIOS — The TI-RTOS Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4 UIA — TI-RTOS Instrumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.5 NDK — TI-RTOS Networking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.6 IPC — TI-RTOS Interprocessor Communication . . . . . . . . . . . . . . . . 10
1.7 FatFS Module in SYS/BIOS — TI-RTOS File System . . . . . . . . . . . . . 11
1.8 TI-RTOS Drivers and Board Initialization . . . . . . . . . . . . . . . . . . . . . . 11
1.9 XDCtools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Topic Page
8About TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
What are the TI-RTOS Components? www.ti.com
1.2 What are the TI-RTOS Components?
TI-RTOS contains its own source files, pre-compiled libraries (both instrumented and non-instrumented),
and examples. Additionally, TI-RTOS contains a number of components within its "
products
"
subdirectory. The components of TI-RTOS are as follows. Some components are not available for all
device families.
Table 1–1. TI-RTOS Components
•
TI-RTOS Kernel — SYS/BIOS. SYS/BIOS is a scalable real-time kernel. It is designed to be used
by applications that require real-time scheduling and synchronization or real-time instrumentation. It
provides preemptive multi-threading, hardware abstraction, real-time analysis, and configuration
tools. SYS/BIOS is designed to minimize memory and CPU requirements on the target.
•
TI-RTOS Instrumentation — UIA. The Unified Instrumentation Architecture (UIA) provides target
content that aids in the creation and gathering of instrumentation data (for example, Log data).
•
TI-RTOS Interprocessor Communication — IPC. IPC contains packages that are designed to
allow communication between processors in a multi-processor environment and communication to
peripherals. This communication includes message passing, streams, and linked lists. These work
transparently in both uni-processor and multi-processor configurations.
•
TI-RTOS Networking — NDK. The Network Developer's Kit (NDK) is a platform for development and
demonstration of network enabled applications on TI embedded processors.
•
MSP430Ware, MWare, and TivaWare. These provide an extensive suite of software designed to
simplify and speed development of applications on the corresponding device family. These
component are rebuilt to include only the portions required by TI-RTOS
•
XDCtools. This core component provides the underlying tooling for configuring and building TI-
RTOS and its components. XDCtools is installed as part of CCSv6. If you install TI-RTOS outside
CCS, a compatible version of XDCtools is installed automatically.
TI-RTOS Component Name PDF Documentation Location
TI-RTOS TI-RTOS examples Chapter 3 of the TI-RTOS Getting Started Guide for your device
TI-RTOS Kernel SYS/BIOS SYS/BIOS (TI-RTOS Kernel) User’s Guide -- SPRUEX3
TI-RTOS Instrumentation UIA System Analyzer User’s Guide -- SPRUH43
TI-RTOS Networking NDK TI Network Developer's Kit (NDK) Guide -- SPRU523
TI Network Developer's Kit (NDK) API Reference -- SPRU524
TI-RTOS Interprocessor
Communication
IPC IPC User’s Guide on Texas Instruments Wiki
TI-RTOS File System FatFS Chapter 7 of this User’s Guide
TI-RTOS USB USB stack Section 5.11 and Section 5.12 of this User’s Guide
TI-RTOS Drivers and
Board Initialization
Drivers and TivaWare,
MSP430Ware, or Mware
Section 1.8 and Chapter 5 of this User’s Guide
SPRUHD4F—April 2014 About TI-RTOS 9
Submit Documentation Feedback
www.ti.com SYS/BIOS — The TI-RTOS Kernel
1.3 SYS/BIOS — The TI-RTOS Kernel
SYS/BIOS is an advanced real-time operating system from Texas Instruments for use in a wide range of
DSPs, microprocessors, and microcontrollers. It is designed for use in embedded applications that need
real-time scheduling, synchronization, and instrumentation. SYS/BIOS is designed to minimize memory
and CPU requirements on the target. SYS/BIOS provides a wide range of services, such as:
•
Preemptive, deterministic multi-threading
•
Hardware abstraction
•
Memory management
•
Configuration tools
•
Real-time analysis
For more information about SYS/BIOS, see the following:
SYS/BIOS User’s Guide (SPRUEX3)
SYS/BIOS online reference (also called "CDOC"). In CCS, choose Help > Help Contents and
expand the TI-RTOS item for your device family. Choose the Config API Reference (cdoc) item and
see help under the ti.sysbios and xdc.runtime modules.
SYS/BIOS on Texas Instruments Wiki
TI-RTOS forum on TI’s E2E Community
1.4 UIA — TI-RTOS Instrumentation
The Unified Instrumentation Architecture (UIA) provides target content that aids in the creation and
gathering of instrumentation data (for example, Log data).
The System Analyzer tool suite, which is part of CCS, provides a consistent and portable way to
instrument software. It includes the views that can be opened from the Tools > RTOS Analyzer and
Tools > System Analyzer menus in CCS. It enables software to be re-used with a variety of silicon
devices, software applications, and product contexts. It works together with UIA to provide visibility into
the real-time performance and behavior of software running on TI's embedded single-core and multicore
devices.
For more information about UIA and System Analyzer, see the following:
System Analyzer User’s Guide (SPRUH43)
UIA online reference (also called "CDOC"). In CCS, choose Help > Help Contents and expand the
TI-RTOS item for your device family. Choose the Config API Reference (cdoc) item and see help
under the ti.uia module.
System Analyzer on Texas Instruments Wiki
10 About TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
NDK — TI-RTOS Networking www.ti.com
1.5 NDK — TI-RTOS Networking
The Network Developer's Kit (NDK) is a platform for development and demonstration of network enabled
applications on TI embedded processors, currently limited to the TMS320C6000 family and ARM
processors. The NDK stack serves as a rapid prototyping platform for the development of network and
packet processing applications. It can be used to add network connectivity to existing applications for
communications, configuration, and control. Using the components provided in the NDK, developers can
quickly move from development concepts to working implementations attached to the network.
The NDK is a networking stack that operates on top of SYS/BIOS.
For more information about NDK, see the following:
NDK User’s Guide (SPRU523)
NDK Programmer’s Reference Guide (SPRU524)
NDK online reference.
Run <tirtos_install>/products/ndk_#_##_##_##/docs/doxygen/html/index.html.
NDK online configuration reference (also called "CDOC"). In CCS, choose Help > Help Contents
and expand the TI-RTOS item for your device family. Choose the Config API Reference (cdoc) item
and see help under the ti.ndk module.
NDK on Texas Instruments Wiki
TI-RTOS forum on TI’s E2E Community
1.6 IPC — TI-RTOS Interprocessor Communication
IPC is a component containing packages that are designed to allow communication between processors
in a multi-processor environment and communication between threads and peripherals in a uni-
processor and multi-processor environment. This communication includes message passing, streams,
and linked lists. These work transparently in both uni-processor and multi-processor configurations.
The ti.sdo.ipc package contains modules and interfaces for interprocessor communication. The
ti.sdo.utils package contains utility modules for supporting the ti.sdo.ipc modules and other modules.
IPC is designed for use on processors running SYS/BIOS applications. IPC can be used to communicate
with the following:
•
Other threads on the same processor
•
Threads on other processors running SYS/BIOS
•
Threads on general purpose processors (GPP) running SysLink
For more information about IPC, see the following:
IPC User’s Guide (SPRUGO6)
IPC online reference. Run <tirtos_install>/products/ipc_#_##_##_##/docs/doxygen/index.html.
IPC online configuration reference (also called "CDOC"). In CCS, choose Help > Help Contents and
expand the TI-RTOS item for your device family. Choose the Config API Reference (cdoc) item and
see help under the ti.ipc module.
SPRUHD4F—April 2014 About TI-RTOS 11
Submit Documentation Feedback
www.ti.com FatFS Module in SYS/BIOS — TI-RTOS File System
1.7 FatFS Module in SYS/BIOS — TI-RTOS File System
FatFS is an open-source FAT file system module intended for use in embedded systems. The API used
by your applications is generic to all FatFS implementations, and is described and documented at
http://elm-chan.org/fsw/ff/00index_e.html. In order to use FatFS in TI-RTOS applications, you must
configure the module for use with the SYS/BIOS ti.sysbios.fatfs.FatFS module.
For more information about FatFS, see the following:
Chapter 7, "Using the FatFs File System Drivers"
FatFS for SYS/BIOS wiki page
SYS/BIOS online reference (also called "CDOC"). In CCS, choose Help > Help Contents and
expand the TI-RTOS item for your device family. Choose the Config API Reference (cdoc) item and
see help under the ti.sysbios.fatfs.FatFS module topic.
1.8 TI-RTOS Drivers and Board Initialization
TI-RTOS provides drivers for device families for which a *Ware package is supported by TI-RTOS. This
*Ware packages include TivaWare, MSP430Ware, and MWare. The *Ware libraries distributed with TI-
RTOS have been reduced in size to include only the necessary portions of the libraries.
1.8.1 Drivers
TI-RTOS includes drivers for a number of peripherals. See Chapter 5 for a list of the specific drivers and
details about each one.
The drivers are in the
<tirtos_install>/packages/ti/drivers
directory. TI-RTOS examples are
provided to show how to use these drivers.
Note that all of these drivers are built on top of MWare, MSP430Ware, and TivaWare. These drivers
provide the following advantages over those provided by MWare, MSP430Ware, and TivaWare:
•
The TI-RTOS drivers are thread-safe for use with SYS/BIOS threads.
•
The TI-RTOS drivers are provided in both instrumented and non-instrumented versions. The
instrumented versions support logging and asserts.
•
The TI-RTOS drivers provide support for the RTOS Object View (ROV) tool in CCS.
1.8.2 MWare
MWare is the M3 portion of controlSUITE, a software package that provides support for F28M3x
(Concerto) devices. It includes low-level drivers and examples.
•
The version of MWare provided with TI-RTOS differs from the version in controlSUITE in that it has
been rebuilt. See the TI-RTOS.README file in the
<tirtos_install>\products\MWare_v###a
directory for more specific details. To indicate that the version has been modified, the name of the
MWare folder has an added letter (beginning with "a" and to be incremented in subsequent versions).
For example
<tirtos_install>\products\MWare_v110a
.
Note that the MWare drivers are not thread-safe. You can use synchronization mechanisms provided by
SYS/BIOS to protect multiple threads that access the same MWare drivers.
12 About TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
TI-RTOS Drivers and Board Initialization www.ti.com
For more information about MWare and controlSUITE, see the following:
Documents in <tirtos_install>/products/MWare_##/docs
controlSUITE on Texas Instruments Wiki
controlSUITE Product Folder
1.8.3 MSP430Ware
MSP430Ware is an extensive suite of drivers, code examples, and design resources designed to simplify
and speed development of MSP430 microcontroller applications. Currently, TI-RTOS uses MSP430Ware
to support MSP430F5xx and MSP430F6xx devices. TI-RTOS utilizes MSP430Ware's driverlib,
usblib430, and grlib components.
•
The version of MSP430Ware provided with TI-RTOS differs from the full version in several ways. See
the TI-RTOS.README file in the
<tirtos_install>\products\MSP430Ware_1_##_##_##a
directory for more specific details. To indicate that the version has been modified, the name of the
MSP430Ware folder has an added letter (beginning with "a" and to be incremented in subsequent
versions). For example
<tirtos_install>\products\MSP430Ware_1_80_01_03a
.
Note that the MSP430Ware drivers are not thread-safe. You can use synchronization mechanisms
provided by SYS/BIOS to protect multiple threads that access the same MSP430Ware drivers.
For more information about MSP430Ware, see the following:
Documents in <tirtos_install>/products/MSP430Ware_#_##_##_##a/doc
Documents in <tirtos_install>/products/MSP430Ware_#_##_##_##a/driverlib/doc/MSP430F5xx_6xx
Documents in <tirtos_install>/products/MSP430Ware_#_##_##_##a/usblib430/
MSP430_USB_Software/Documentation
MSP430Ware Product Folder
1.8.4 TivaWare
This software is an extensive suite of software designed to simplify and speed development of Tiva-
based (ARM Cortex-M) microcontroller applications. (TivaWare was previously called StellarisWare.)
The version of TivaWare provided with TI-RTOS differs from the standard release in that it has been
rebuilt. See the TI-RTOS.README file in the
<tirtos_install>\products\TivaWare_C_Series-1.#
directory for more specific details.
Note that the TivaWare drivers are not thread-safe. You can use synchronization mechanisms provided
by SYS/BIOS to protect multiple threads that access the same TivaWare drivers.
For more information about TivaWare, see the following:
Documents in <tirtos_install>/products/TivaWare_####/docs
TivaWare Product Folder
Online StellarisWare Workshop
SPRUHD4F—April 2014 About TI-RTOS 13
Submit Documentation Feedback
www.ti.com XDCtools
1.9 XDCtools
XDCtools is a separate software component provided by Texas Instruments that provides the underlying
tooling needed for configuring and building SYS/BIOS, IPC, NDK, and UIA.
TI-RTOS installs XDCtools only if the version needed by TI-RTOS has not already been installed as part
of a CCS or SYS/BIOS installation. If TI-RTOS installs XDCtools, it places it in the top-level CCS directory
(for example, c:\ti), not the TI-RTOS products directory.
•
XDCtools provides the XGCONF Configuration Editor and the scripting language used in the *.cfg
files. This is used to configure modules in a number of the components that make up TI-RTOS.
•
XDCtools provides the tools used to build the configuration file. These tools are used automatically
by CCS if your project contains a *.cfg file. This build step generates source code files that are then
compiled and linked with your application code.
•
XDCtools provides a number of modules and runtime APIs that TI-RTOS and its components
leverage for memory allocation, logging, system control, and more.
XDCtools is sometimes referred to as "RTSC" (pronounced "rit-see"—Real Time Software Components),
which is the name for the open-source project within the Eclipse.org ecosystem for providing reusable
software components (called "packages") for use in embedded systems. For more about how XDCtools
and SYS/BIOS are related, see the SYS/BIOS User’s Guide (SPRUEX3).
For more information about XDCtools, see the following:
XDCtools online reference (also called "CDOC").
Open from CCS help or run <xdctools_install>/docs/xdctools.chm.
RTSC-Pedia Wiki
TI-RTOS forum on TI’s E2E Community
SPRUHD4F—April 2014 Instrumentation with TI-RTOS 14
Submit Documentation Feedback
Chapter 2
SPRUHD4F—April 2014
Instrumentation with TI-RTOS
This chapter describes how to instrument your application with log calls and view the data with System
Analyzer (SA).
2.1 Overview
TI-RTOS uses the Unified Instrumentation Architecture (UIA) to instrument your application with log calls.
The data can be viewed and visualized with System Analyzer (SA) to create execution graphs, load
graphs and more. For detailed information on using UIA and SA refer to the Getting Started Guide in the
<tirtos_install>/products/uia_#_##_##_##/docs directory and the System Analyzer User’s Guide
(SPRUH43).
Note that System Analyzer includes the views that can be opened from both the
Tools > RTOS Analyzer
and T
ools > System Analyzer
menus in CCS. That is, the RTOS Analyzer tools in CCS are part of
System Analyzer.
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.2 Adding Logging to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.3 Modifying an Example to Upload Logging Data at Runtime . . . . . . . 17
2.4 Using Log Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.5 Viewing the Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Topic Page
SPRUHD4F—April 2014 Instrumentation with TI-RTOS 15
Submit Documentation Feedback
www.ti.com Adding Logging to a Project
2.2 Adding Logging to a Project
To add SYS/BIOS logging to a project, follow these steps:
1. Double-click on the configuration file (.cfg) for your project to open it with the XGCONF Configuration
Editor.
2. If LoggingSetup is already listed in your Outline pane, skip to Step 5.
3. In the "Available Products" area, expand the list as shown here to find the
LoggingSetup
module in
the UIA product.
4. Right-click on the LoggingSetup module, and select
Use LoggingSetup
. This adds the
LoggingSetup module to your project and opens the configuration page for the module.
16 Instrumentation with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Adding Logging to a Project www.ti.com
5. Use the configuration page for the LoggingSetup module as follows:
a) In the
Built-in Software Instrumentation
area, use the check boxes to select what types of
threads you want to be logged for execution analysis, including tasks, software interrupts (Swi),
and hardware interrupts (Hwi). If you check the
Run-time control of Event Logging
box, you
can turn that type of logging on or off at runtime.
b) Also in the
Built-in Software Instrumentation
area, you can check boxes if you want the CPU
load to be logged for various types of activity.
c) In the
User-written Software Instrumentation
area, you can enable logging of any additional
instrumentation you have added with application code.
d) In the
Loggers
area, you configure the logger to use in your main application. Calls to Log_info(),
Log_warning(), and Log_error() in your main application as well as any instrumented driver logs
will be sent to this logger. By default, LoggingSetup creates a logger that sends events over
JTAG when the target is halted (that is, in Stop Mode).
The examples provided with TI-RTOS include and configure the LoggingSetup module. For more
information on using LoggingSetup refer to Section 5.3.1 in the System Analyzer User’s Guide
(SPRUH43).
SPRUHD4F—April 2014 Instrumentation with TI-RTOS 17
Submit Documentation Feedback
www.ti.com Modifying an Example to Upload Logging Data at Runtime
2.3 Modifying an Example to Upload Logging Data at Runtime
The UART Console example uses UIA to upload logging data at runtime to RTOS Analyzer and System
Analyzer views in CCS. All other TI-RTOS examples, including UART Echo, use Stop Mode uploading of
such data. This section provides the steps to modify the UART Echo example to use the USB for the
same type of runtime data uploading performed by the UART Console example. These steps can be
adapted to other TI-RTOS examples.
In order to change from stop mode to runtime uploading, you need to make changes to the UART Echo
project, code, and configuration as described in the following pages.
2.3.1 Project Changes
Add the following two files to your UART Echo project:
•
USBCDCD_LoggerIdle.c
•
USBCDCD_LoggerIdle.h
These two files are included in the UART Console example. You can choose
Project > Add Files
in CCS
and copy them into your project from the
<tirtos_install>/packages/examples
directory.
The UART Echo examples already include the appropriate USB library. This library is provided by
MWare, TivaWare, and MSP430Ware. If you are modifying an example other than UART Echo, add the
appropriate library from the following list to your project:
•
<tirtos_install>\products\MWare_v20#a\MWare\usblib\ccs\Debug\usblib.lib
•
<tirtos_install>\products\TivaWare_C_Series-2.#a\usblib\ccs\Debug\usblib.lib
•
<tirtos_install>\products\MSP430Ware_1_##_##_##a\driverlib\ccs-MSP430F5529\ccs-
MSP430F5529.lib
To add a library to a CCS project, follow these steps:
1. Right-click on the project name in the Project Explorer pane of CCS and select
Properties
from the
context menu.
2. Expand the
Build > Linker
category and select the
File Search Path
category.
3. Click the
+
button over the
Include library file or command file as input
field.
4. Click
File System
in the Add file path dialog.
5. Browse to the location of the appropriate usblib library, and select the library file. Click
Open
.
6. Click
OK
in the Add file path dialog.
18 Instrumentation with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Modifying an Example to Upload Logging Data at Runtime www.ti.com
7. Click
OK
in the Properties dialog.
SPRUHD4F—April 2014 Instrumentation with TI-RTOS 19
Submit Documentation Feedback
www.ti.com Modifying an Example to Upload Logging Data at Runtime
2.3.2 Code Changes
Open the uartecho.c file in CCS and add the following code:
•
Include the USBCDCD_LoggerIdle.h header file:
•
Add the calls to Board_initUSB() and USBCDCD_init() to the main() function as shown in green
below:
#include "USBCDCD_LoggerIdle.h"
Int main(Void)
{
Error_Block eb;
Task_Params taskParams;
/* Call board init functions. */
Board_initGeneral();
Board_initGPIO();
Board_initUART();
Board_initUSB(Board_USBDEVICE);
System_printf("Starting the example\nSystem provider is set to SysMin,"
"halt the target and use ROV to view output.\n");
/* SysMin will only print to the console when you call flush or exit */
System_flush();
/* Turn on user LED */
GPIO_write(Board_LED, Board_LED_ON);
/* Initialize the USB CDC device for logging transport */
USBCDCD_init();
/* Create the task */
Error_init(&eb);
Task_Params_init(&taskParams);
taskParams.instance->name = "echo";
echo = Task_create(echoFxn, &taskParams, &eb);
if (echo == NULL) {
System_printf("Task was not created\n");
System_abort("Aborting...\n");
}
/* Enable interrupts and start SYS/BIOS */
BIOS_start();
return (0);
}
20 Instrumentation with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Modifying an Example to Upload Logging Data at Runtime www.ti.com
2.3.3 Configuration Changes
You can modify the project’s configuration with the XGCONF Configuration Editor or with a text editor.
Here are the steps for both of these methods:
1. Using the XGCONF Configuration Editor, open the UART Echo project's uartecho.cfg file.
2. Select the
LoggingSetup
module in the Outline pane.
3. In the LoggingSetup configuration page, move to the
Loggers
section and change the logger type
to
LoggerIdle - Upload in Idle loop
.
4. Follow the
Please click here to configure the LoggerIdle module
link.
SPRUHD4F—April 2014 Instrumentation with TI-RTOS 21
Submit Documentation Feedback
www.ti.com Modifying an Example to Upload Logging Data at Runtime
5. In the Logger Idle configuration page, check the
Add the LoggerIdle module to my configuration
box.
6. Set the
Buffer Size
to 1024.
Set the
Transport Function
to USBCDCD_LoggerIdle_sendData,
Set the
Transport Type
to TransportType_USB.
7. Save the configuration file.
To modify the configuration with a text editor, add the following statements at the end of the uartecho.cfg
file:
Note:
The configuration file should already contain the following statement:
LoggingSetup.loggerType = LoggingSetup.LoggerType_IDLE;
LoggerIdle.transportType = LoggerIdle.TransportType_USB;
LoggerIdle.bufferSize = 1024;
LoggerIdle.transportFxn = "&USBCDCD_LoggerIdle_sendData";
var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
22 Instrumentation with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Using Log Events www.ti.com
2.4 Using Log Events
You can add Log events to your application and control whether Log events are processed by drivers as
described in the following sub-sections.
2.4.1 Adding Log Events to your Code
Your application can send messages to a Log using the standard Log module APIs (xdc.runtime.Log).
Log calls are of the format
Log_typeN(String, arg1, arg2… argN)
. Valid types are print, info, warning
and error. N is the number of arguments between 0 and 5. For example:
See the SYS/BIOS Log example project for more use cases.
2.4.2 Using Instrumented or Non-Instrumented Libraries
TI-RTOS drivers allow you to control whether Log events are handled by choosing to build with the
instrumented or non-instrumented libraries. The instrumented libraries process Log events while the non-
instrumented libraries do not.
To select the type of library to build with, follow these steps:
1. Double-click on the configuration file (.cfg) for your project to
open it with the XGCONF Configuration Editor.
2. In the “Available Products” area, select the TI-RTOS driver
whose behavior you want to control. For example, some of the
drivers you can configure are the EMAC, GPIO, I
2
C, SDSPI,
UART, USBMSCHFatFs, and Watchdog drivers.
3. On the configuration page, choose whether to use the
instrumented or non-instrumented libraries.
Refer to the individual drivers in Chapter 5 for details about what is
logged and which Diags masks are used.
Log_info2("tsk1 Entering. arg0,1 = %d %d", arg0, arg1)
SPRUHD4F—April 2014 Instrumentation with TI-RTOS 23
Submit Documentation Feedback
www.ti.com Viewing the Logs
2.5 Viewing the Logs
You can use CCS to view Log messages using the RTOS Analyzer, System Analyzer, and/or ROV tools.
2.5.1 Using RTOS Analyzer and System Analyzer
After you have built and run your application, follow these steps in the CCS Debug view to see Log
messages from your application with RTOS Analyzer:
1. Open an analyzer by selecting
Tools > RTOS Analyzer > Printf and Error Logs
.
2. The Analysis Configuration detects the type of transport you are using.
3. Select additional analyzer views you would like to run.
4. Configure the analyzer to run for a set time or forever (that is, until you manually pause the data
transfer). You can also choose when to process the data (Transport Data only after collection),
whether to clear existing data and save the data to a file which can be imported back into SA.
24 Instrumentation with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Viewing the Logs www.ti.com
If you save data to a file, you can analyze it later by selecting
Tools > RTOS Analyzer > Open File >
Open Binary File
.
See Section 4.2 ("Starting an RTOS Analyzer or System Analyzer Session") in the System Analyzer
User’s Guide (SPRUH43) for more about using this dialog.
2.5.2 Viewing Log Records in ROV
The RTOS Object View (ROV) can be used to view log events stored on the target.
After you have built and run your application, you can open the ROV tool in the CCS Debug view by
selecting
Tools > RTOS Object View (ROV)
and then navigating to the logging module you want to view
(for example, LoggerStopMode or LoggerIdle). When the target is halted, ROV repopulates the data.
Select the
Records
tab to view log events still stored in the buffer. For loggers configured to use JTAG,
the records shown here are also uploaded to System Analyzer. If you are using the LoggerIdle module,
these are the records that have not yet been sent.
See the http://rtsc.eclipse.org/docs-tip/RTSC_Object_Viewer web page for more about using the RTOS
Object View (ROV) tool.
SPRUHD4F—April 2014 Debugging TI-RTOS Applications 25
Submit Documentation Feedback
Chapter 3
SPRUHD4F—April 2014
Debugging TI-RTOS Applications
This chapter provides information about ways to debug your TI-RTOS applications.
3.1 Using CCS Debugging Tools
Within Code Composer Studio (CCS), there are several tools you can use to debug your TI-RTOS
applications:
•
RTOS Object View (ROV)
is a stop-mode debugging tool, which means it can receive data about an
application only when the target is halted, not when it is running. ROV is a tool provided by the
XDCtools component. ROV gets information from many of the modules your applications are likely
to use.
The ROV tool is also available for use with TI-RTOS examples within IAR Embedded Workbench.
See the TI-RTOS Getting Started Guide (SPRUHD3) for details.
3.1 Using CCS Debugging Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.2 Generating printf Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.3 Controlling Software Versions for Use with TI-RTOS . . . . . . . . . . . . 30
3.4 Understanding the Build Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Topic Page
26 Debugging TI-RTOS Applications SPRUHD4F—April 2014
Submit Documentation Feedback
Using CCS Debugging Tools www.ti.com
•
System Analyzer
includes analysis features for viewing the CPU and thread loads, the execution
sequence, thread durations, and context profiling. The features include graphs, detailed logs, and
summary logs. These views gather data from the UIA component. For information, see the System
Analyzer User’s Guide (SPRUH43).
•
Printf-style output
lets you use the tried-and-true debugging mechanism of sending execution
information to the console. For information, see “Generating printf Output” on page 27.
•
Standard CCS IDE features
provide many tools for debugging your applications. In CCS, choose
Help > Help Contents
and open the
Code Composer Help > Views and Editors
category for a list
of debugging tools and more information. These debugging features include:
—
Source-level debugger
—
Assembly-level debugger
—
Breakpoints (software and hardware)
—
Register, memory, cache, variable, and expression views
—
Pin and port connect views
—
Trace Analyzer view
•
Exception Handling
is provided by SYS/BIOS. If this module is enabled, the execution state is
saved into a buffer that can be viewed with the ROV tool when an exception occurs. Details of the
behavior of this module are target-specific. In the CCS online help, see the SYS/BIOS API Reference
help on the ti.sysbios.family.c64p.Exception module or the ti.sysbios.family.arm.exc.Exception
module for details.
•
Assert Handling
is provided by XDCtools. It provides configurable diagnostics similar to the
standard C assert() macro. In the CCS online help, see the XDCtools API Reference help on the
xdc.runtime.Assert module for details.
SPRUHD4F—April 2014 Debugging TI-RTOS Applications 27
Submit Documentation Feedback
www.ti.com Generating printf Output
3.2 Generating printf Output
Along with many advanced GUI debugging features described in “Using CCS Debugging Tools” on
page 25, TI-RTOS provides flexibility with the tried-and-true printf method of debugging. TI-RTOS
supports both the standard printf() and a more flexible replacement called System_printf().
3.2.1 Output with printf()
By default, the printf() function outputs data to a CIO buffer on the target. When CCS is attached to the
target (for example, via JTAG or USB), the printf() output is displayed in the Console window. It is
important to realize that when the CIO buffer is full or a ‘\n’ is output, a CIO breakpoint is hit on the target.
This allows CCS to read the data and output the characters to the console. Once the data is read, CCS
resumes running the target. This interruption of the target can have significant impact on a real-time
system. Because of this interruption and the associated performance overhead, use of the printf() API is
discouraged.
The UART Console example shows how to route the printf() output to a UART via the add_device() API.
3.2.2 Output with System_printf()
The xdc.runtime.System module provided by the XDCtools component offers a more flexible and
potentially better-performing replacement to printf() called System_printf().
The System module allows different low-level implementations (System Support implementations) to be
plugged in based on your needs. You can plug in the System Support implementation you want to use
via the application configuration. Your choice does not require any changes to the runtime code.
Currently the following System Support implementations are available:
•
SysMin:
Stores output to an internal buffer. The buffer is flushed to stdout (which goes to the CCS
Console view) when System_flush() is called or when an application terminates (for example, when
BIOS_exit() or exit() is called). When the buffer is full, the oldest characters are over-written.
Characters that have not been sent to stdout can be viewed via the RTOS Object View (ROV) tool.
The SysMin module is part of the XDCtools component. Its full module path is xdc.runtime.SysMin.
•
SysFlex:
Allows a user to plug in their functions. The SysFlex module has been deprecated.
Applications should use the xdc.runtime.SysCallback module instead.
•
SysCallback:
Simply calls user-defined functions that implement the System module's functionality.
The UART Console example provides a set of functions that use the UART. The SysCallback module
is part of the XDCtools component. Its full module path is xdc.runtime.SysCallback.
•
SysStd:
Sends the characters to the standard printf() function. The SysStd module is part of the
XDCtools component. Its full module path is xdc.runtime.SysStd.
Most TI-RTOS examples use either the SysMin or SysStd module. The UART Console example uses
SysCallback and routes the output to a UART.
28 Debugging TI-RTOS Applications SPRUHD4F—April 2014
Submit Documentation Feedback
Generating printf Output www.ti.com
To configure the SysMin module, open the application’s *.cfg file with the XGCONF Configuration Editor.
In the Outline area, select the System module. Configure the System Provider to use SysMin as follows:
Then, find the SysMin module in the Outline pane, and configure the output buffer and options as needed.
For example, here are the settings used by most examples provided with TI-RTOS:
The following statements create the same configuration as the graphical settings shown for the System
and SysMin modules:
var System = xdc.useModule('xdc.runtime.System');
var SysMin = xdc.useModule('xdc.runtime.SysMin');
System.SupportProxy = SysMin;
SPRUHD4F—April 2014 Debugging TI-RTOS Applications 29
Submit Documentation Feedback
www.ti.com Generating printf Output
The following table shows the pros and cons of the various System provider modules:
Please note, the System module also provides the additional APIs that can be used instead of standard
‘C’ functions: System_abort(), System_atexit(), System_exit(), System_putch(), and System_flush().
Table 3-1 System providers shipped with TI-RTOS
System Provider Pros Cons
SysMin
•
Good performance
•
Requires RAM (but size is configurable)
•
Potentially lose data
•
Out-of-box experience
•
To view in CCS console, you must add System_flush()
or have the application terminate
•
Can use ROV to view output, but requires you halt the
target
SysStd
•
Easy to use (just like printf)
•
Bad to use (just like printf). CCS halts target when CIO
buffer is full or a ‘\n’ is written
•
Cannot be called from a SYS/BIOS Hwi or Swi thread
SysCallback
•
Can be used for many custom
purposes
•
Requires that you provide your own callback functions
30 Debugging TI-RTOS Applications SPRUHD4F—April 2014
Submit Documentation Feedback
Controlling Software Versions for Use with TI-RTOS www.ti.com
3.3 Controlling Software Versions for Use with TI-RTOS
You do not need to add the "products" subdirectory to the RTSC (also called XDCtools) discovery path.
Once CCS has found the main TI-RTOS directory, it will also find the additional components provided in
that tree.
In addition, the components installed with TI-RTOS will be used as needed by examples you import with
the TI Resource Explorer. When you choose
Project > Properties
for a project that uses TI-RTOS, the
sub-components are not checked in the
RTSC
tab of the
General
category. However, the version
installed with TI-RTOS is automatically used for sub-components that are needed by the example. You
can see these components and which versions are used by going to the
Order
tab.
If, at a later time, you install newer software versions that you want to use instead of the versions installed
with TI-RTOS, you can use the
Products and Repositories
tab to add those versions to your project
and the
Up
and
Down
buttons in the
Orders
tab to make your newer versions take precedence over the
versions installed with TI-RTOS. However, you should be aware that is it possible that newer component
versions may not be completely compatible with your version of TI-RTOS.
Note that in the
RTSC
tab, the XDCtools version in the drop-down list is the version that controls UI
behavior in CCS, such as the XGCONF editor and various RTSC dialog layouts. The XDCtools version
in the list of products is the version used for APIs and configuration, such as the xdc.runtime modules.
SPRUHD4F—April 2014 Debugging TI-RTOS Applications 31
Submit Documentation Feedback
www.ti.com Understanding the Build Flow
3.4 Understanding the Build Flow
The build flow for TI-RTOS applications begins with an extra step to process the configuration file (*.cfg)
in the project. The configuration file is a script file with syntax similar to JavaScript. You can edit it
graphically in CCS using the XGCONF Configuration Editor. The configuration determines which
modules in TI-RTOS components are used, sets global behavior parameters for modules, and statically
creates objects managed by the modules. Static configuration has several advantages, including
reducing code memory use by the application. Components that can be configured using this file include
XDCtools, SYS/BIOS, TI-RTOS, IPC, NDK, and UIA.
The configuration file is processed by the XDCtools component. If you look at the messages printed
during the build, you will see a command line that runs the “xs” executable in the XDCtools component
with the “xdc.tools.configuro” tool specified. For example:
In CCS, you can control the command-line options used with XDCtools by choosing
Project > Properties
from the menus and selecting the
Build > XDCtools
category.
Target settings for processing your individual project are in the
RTSC
tab of the
CCS General
category.
(RTSC is the name for the Eclipse specification implemented by XDCtools.)
When XDCtools processes your *.cfg file, the code is generated in the <project_dir>/Debug/configPkg
directory. This code is compiled so that it can be linked with your final application. In addition, a
compiler.opt file is created for use during program compilation, and a linker.cmd file is created for use in
linking the application. You should not modify the files in the <project_dir>/Debug/configPkg directory
after they are generated, since they will be overwritten the next time you build.
For more information about the build flow, see Chapter 2 of the SYS/BIOS User’s Guide (SPRUEX3). For
command-line details about xdc.tools.configuro, see the RTSC-pedia reference topic.
'Invoking: XDCtools'
"<>/xs" --xdcpath="<tirtos_install>/packages;
<bios_install>/packages;<uia_install>/packages;" xdc.tools.configuro -o configPkg
-t ti.targets.arm.elf.M3 -p ti.platforms.concertoM3:F28M35H52C1 -r release
-c "C:/ccs/ccsv6/tools/compiler/tms470" "../<project>.cfg"
SPRUHD4F—April 2014 Board-Specific Files 32
Submit Documentation Feedback
Chapter 4
SPRUHD4F—April 2014
Board-Specific Files
This chapter provides information that is specific to targets for which you can use TI-RTOS.
4.1 Overview
Currently, TI-RTOS provides examples for the following boards:
F28M3x devices contain both M3 and 28x subsystems.
TI-RTOS can also be used on other boards. Examples are provided specifically for the supported boards,
but libraries are provided for each of these device families, so that you can port the examples to similar
boards. The Texas Instruments Wiki contains a TI-RTOS Porting Guide and a topic on Creating TI-RTOS
Projects for Other MSP430 Devices.
Family Device on Board Board
Concerto (ARM M3 + DSP 28x) F28M35H52C1 TMDXDOCKH52C1 Experimenter Kit
Concerto (ARM M3 + DSP 28x) F28M36P63C2 TMDXDOCK28M36 Experimenter Kit
ARM (Tiva) TM4C123GH6PM EK-TM4C123GXL LaunchPad
ARM (Stellaris) LM4F120H5QR EK-LM4F120XL LaunchPad
(earlier version of EK-TM4C123GXL LaunchPad)
ARM (Tiva) TM4C123GH6PGE DK-TM4C123G Evaluation Kit
ARM (Stellaris) LM4F232H5QD EKS-LM4F232 Evaluation Kit
(earlier version of DK-TM4C123G Evaluation Kit)
ARM (Tiva) Cortex-M4F TM4C129XNCZAD DK-TM4C129X Evaluation Kit
ARM (Tiva) TM4C1294NCPDT EK_TM4C1294XL Evaluation Kit
MSP430F5xx/6xx MSP430F5529 MSP-EXP430F5529LP LaunchPad
MSP430F5xx/6xx MSP430F5529 MSP-EXP430F5529 Experimenter Board
MSP430F5xx/6xx MSP430FR5969 MSP-EXP430FR5969LP LaunchPad
4.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.2 Board-Specific Code Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.3 Linker Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4 Target Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Topic Page
SPRUHD4F—April 2014 Board-Specific Files 33
Submit Documentation Feedback
www.ti.com Board-Specific Code Files
4.2 Board-Specific Code Files
TI-RTOS examples contain a board-specific C file (and its companion header file). The filenames are
<board>.c and <board>.h, where <board> is the name of the board, such as TMDXDOCKH52C1. Notice
that an underscore is used in place of a hyphen in file and folder names for board names that contain a
hyphen, such as EKS-LM4F232.
All the examples for a specific board have identical <board> files. These files are considered part of the
application, and you can modify them as needed.
The board-specific code files do not perform any dynamic memory allocation.
The <board> files perform board-specific configuration of the drivers provided by TI-RTOS. For example,
they perform the following:
•
GPIO port and pin configuration
•
LED configuration
•
SDSPI configuration
In addition, the board-specific files provide the following functions that you can use in your applications,
These are typically called from main(). Files are provided only for boards on which the driver is supported.
•
<board>_initDMA() function
•
<board>_initEMAC() function
•
<board>_initGeneral() function
•
<board>_initGPIO() function
•
<board>_initI2C() function
•
<board>_initSDSPI() function
•
<board>_initSPI() function
•
<board>_initUART() function
•
<board>_initUSB() function
•
<board>_initUSBMSCHFatFs() function
•
<board>_initWatchdog() function
•
<board>_initWiFi() function
4.3 Linker Command Files
All of TI-RTOS examples contain a <board>.cmd linker command file. A different file is provided for each
supported board. These files define memory segments and memory sections used by the application.
34 Board-Specific Files SPRUHD4F—April 2014
Submit Documentation Feedback
Target Configuration Files www.ti.com
4.4 Target Configuration Files
To create a target configuration for an example provided with TI-RTOS, use Step 3 (Debugger
Configuration) in the TI Resource Explorer. (To create TI-RTOS example projects using the TI Resource
Explorer, see Chapter 3 of the TI-RTOS Getting Started Guide.)
When you click the link for Step 3, you see the Debugger Configuration dialog. Choose an emulator from
the list. For the F28M3x devices, choose the
Texas Instruments XDS 100v2 USB Emulator
. For Tiva
devices, choose the
Stellaris In-Circuit Debug Interface
. For MSP430 devices, choose the
TI MSP430
USB1
.
The Debugger Configuration step creates a CCS Target Configuration File (*.ccxml). This file specifies
the connection and device for the project for use in a debugging session. You can choose
View > Target
Configurations
in CCS to see and edit these files.
Note:
If you want to use a simulator instead of a hardware connection, select any emulator in
the Debugger Configuration dialog and click
OK
. Then choose
View > Target
Configurations.
Expand the
Projects
list and double-click on the *.ccxml file for your
example project to open the target configuration editor. Select
Texas Instruments
Simulator
in the Connection field, and the simulator for your device in the Device list.
Then click
Save
.
For the F28M3x Demo example, you should not use a C28 target configuration. Instead, use the target
configuration for the M3 and connect to the C28 and load that application manually as described in the
example’s readme file.
SPRUHD4F—April 2014 TI-RTOS Drivers 35
Submit Documentation Feedback
Chapter 5
SPRUHD4F—April 2014
TI-RTOS Drivers
This chapter provides information about the drivers provided with TI-RTOS.
5.1 Overview
TI-RTOS includes drivers for a number of peripherals. These drivers are in the
<tirtos_install>/packages/ti/drivers
directory. TI-RTOS examples show how to use these
drivers. Note that all of these drivers are built on top of MWare, MSP430Ware, and TivaWare. This
chapter contains a section for each driver.
•
EMAC.
Ethernet driver used by the networking stack (NDK) and not intended to be called directly.
•
GPIO.
API set intended to be used directly by the application or middleware to manage the GPIO
interrupts, pins, and ports (and therefore the LEDs).
•
I
2
C.
API set intended to be used directly by the application or middleware.
•
SDSPI.
SPI-based SD driver used by FatFs and not intended to be interfaced directly.
5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.2 Driver Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.3 EMAC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.4 UART Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.5 I2C Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
5.6 GPIO Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.7 SPI Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.8 SPIMessageQTransport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.9 SDSPI Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.10 USBMSCHFatFs Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
5.11 USB Reference Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
5.12 USB Device and Host Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5.13 Watchdog Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
5.14 WiFi Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Topic Page
36 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
Driver Framework www.ti.com
•
SPI.
API set intended to be used directly by the application or middleware to communicate with the
Serial Peripheral Interface (SPI) bus. This driver has been designed to operate in an RTOS
environment such as SYS/BIOS. It protects SPI transactions with OS primitives supplied by
SYS/BIOS. SPI is sometimes called SSI (Synchronous Serial Interface).
•
UART.
API set intended to be used directly by the application to communicate with the UART.
•
USBMSCHFatFs.
USB MSC Host under FatFs (for flash drives). This driver is used by FatFS and is
not intended to be called directly.
•
Other USB functionality.
See the USB examples for reference modules that provide support for the
Human Interface Device (HID) class (mouse and keyboard) and Communications Device Class
(CDC). This code is provided as part of the examples, not as a separate driver.
•
Watchdog.
API set for use directly by the application or middleware to manage the Watchdog timer.
•
WiFi.
Driver used by a Wi-Fi device's host driver to exchange commands, data, and events between
the host MCU and the wireless network processor. Not intended to be interfaced directly.
In addition, TI-RTOS provides the following MessageQ transport:
•
SPIMessageQTransport.
Transport for the SPI driver for use in multicore applications that use the
IPC component.
5.2 Driver Framework
TI-RTOS drivers have a common framework for static configuration and for a set of APIs that all drivers
implement. This section describes that common framework. The driver-specific sections after the
framework description provide details about individual implementations.
5.2.1 Static Configuration
All TI-RTOS drivers have a configuration module that must be included in an application’s configuration
file (.cfg) in order for that application to use the driver. The configuration module pulls in the correct library
for the driver based on the device and instrumentation selected. In addition, it enables use of the RTOS
Object View (ROV) tool for the driver.
SPRUHD4F—April 2014 TI-RTOS Drivers 37
Submit Documentation Feedback
www.ti.com Driver Framework
Add a driver module to the configuration graphically by selecting the module in the Available Products
view and checking the "Add Driver to my configuration" box (where Driver is the TI-RTOS driver name).
Alternately you can edit the configuration file with a text editor. Add the following lines, where
Driver
is
the TI-RTOS driver name. If you omit the second line, the instrumented libraries are used by default.
var Driver = xdc.useModule('ti.drivers.Driver');
Driver.libType = Driver.LibType_Instrumented;
38 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
Driver Framework www.ti.com
5.2.2 Driver Object Declarations
All TI-RTOS drivers require the application to allocate data storage and define a set of data structures
with specific hardware attributes. Drivers are designed in a two-tier hierarchy to facilitate scalable driver
additions and enhancements while providing a consistent application programming interface.
This diagram shows the relationship between a driver interface and two driver implementations. The
driver interface named "Driver" is configured to operate on two driver implementations: "DriverA" and
"DriverB". The driver's Driver_config[] structure contains three instances. The first two instances are of
type "DriverA" and the third is of type "DriverB".
“board.c”
#include <ti/drivers/Driver.h>
#include <ti/drivers/driver/DriverA.h>
#include <ti/drivers/driver/DriverB.h>
DriverA_Object driverA_object[2];
const DriverA_HWAttrs driverA_hwattrs[2] = {…};
DriverB_Object driverB_object;
const DriverB_HWAttrs driverB_hwattrs = {…};
const Driver_Config Driver_config[] = {
{&driverA_fnxTable, &driverA_object[0], &driverA_hwattrs[0]},
{&driverA_fnxTable, &driverA_object[1], &driverA_hwattrs[1]},
{&driverB_fnxTable, &driverB_object, &driverB_hwattrs},
…
{NULL, NULL, NULL}
}
Driver Interface
ti/drivers/Driver.h
typedef struct Driver_FxnTable {
Driver_closeFxn closeFxn;
Driver_initFxn initFxn;
Driver_openFxn openFxn;
...
Driver_funcN funcNFxn;
} Driver_FxnTable;
typedef struct Driver_Config {
Driver_FxnTable const *fxnTablePtr;
Void *object;
Void const *hwAttrs;
} Driver_Config;
Driver Implementation
ti/drivers/driver/DriverA.h
extern Driver_FxnTable driverA_fxnTable;
typedef struct DriverA_Object {
/* Specific object vars */
};
typedef struct DriverA_HWAttrs {
/* Specific hardware attributes */
};
Driver Implementation
ti/drivers/driver/DriverB.h
extern Driver_FxnTable driverB_fxnTable;
typedef struct DriverB_Object {
/* Specific object vars */
};
typedef struct DriverB_HWAttrs {
/* Specific hardware attributes */
};
Joined at link-time
Purpose
Specify the number of peripheral instances
Allocate the proper data object and hardware attributes for a given driver
implementation
Scalable expansion for varies driver implementations.
Driver hardware attribute structures are owned and customizable by the application
SPRUHD4F—April 2014 TI-RTOS Drivers 39
Submit Documentation Feedback
www.ti.com Driver Framework
Applications interface with a TI-RTOS driver using a top-level driver interface. This interface is configured
via a set of data structures that specify one or more specific lower-level driver implementations. Driver
interfaces define data structures in
<tirtos_install>\packages\ti\drivers\Driver.h
while driver
implementations are define in an additional subdirectory, named after the driver interface. For example,
the UART driver interface resides at
<tirtos_install>\packages\ti\drivers\UART.h
and its driver
implementations exist in the
<tirtos_install>\packages\ti\drivers\uart\
subdirectory.
5.2.2.1 Driver Interface
Each driver's interface defines a configuration data structure as:
typedef struct Driver_Config {
Driver_FxnTable const *fxnTablePtr;
Void *object;
Void const *hwAttrs;
} Driver_Config;
(The GPIO driver is an exception. Its GPIO_Config structure contain only a *hwAttrs field.)
40 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
Driver Framework www.ti.com
The application must declare a NULL-terminated array of Driver_Config elements as
Driver_config[]
.The index argument in a driver's _open() call is used to select the array element of
this
Driver_config[]
array where each element corresponds to a peripheral instance. There is no
correlation between the index and the peripheral designation (such as UART0 or UART1). For example,
it is possible to use UART_config[0] for UART1.
Each individual Driver_Config element must be populated by pointers to a specific driver
implementation's Driver_FxnTable, Driver_Object, and Driver_HWAttrs data structures. While the
function table is defined by the driver implementation, the implementation specific data object and
hardware attribute structures need to be defined by the application. With this Driver_config[] table, it is
possible to use any number of permutations of driver implementations per driver interface; assuming that
the device has the same number of peripherals available.
5.2.2.2 Driver Implementations
The application needs to create instances of both the object and hardware attribute structures for every
peripheral used with a given driver implementation. Instances of data objects are used to store driver
variables on a per peripheral basis and should be accessed exclusively by the driver. Hardware attribute
structures are used to specify implementation-specific constants such as peripheral base addresses,
interrupt vectors, GPIO ports, pins, and more. Field definitions for these hardware attributes are
determined by the driver implementation's Doxygen documentation.
All TI-RTOS examples use a <board>.c file that contains necessary data object and hardware structure
instances, similar to the following:
static DriverA_Object driverAObject;
const DriverA_HWAttrs driverAHWAttrs = {
type field0;
type field1;
...
type fieldn;
};
These structures should be used as a reference when moving from a development board to a custom
printed circuit board. The following is an example that integrates a UART driver implementation into the
UART driver interface:
/* UART objects */
UARTTiva_Object uartTivaObjects[EKS_LM4F232_UARTCOUNT];
/* UART configuration structure */
const UARTTiva_HWAttrs uartTivaHWAttrs [EKS_LM4F232_UARTCOUNT] = {
{UART0_BASE, INT_UART0}, /* UART0 */
};
const UART_Config UART_config[] = {
{&UARTTiva_fxnTable, &uartTivaObjects[0], &uartTivaHWAttrs[0]},
{NULL, NULL, NULL}
};
SPRUHD4F—April 2014 TI-RTOS Drivers 41
Submit Documentation Feedback
www.ti.com Driver Framework
5.2.3 Dynamic Configuration and Common APIs
TI-RTOS drivers all implement the following APIs (with the exception of the GPIO driver*).
•
Void Driver_init(Void)
—
Initializes the driver. Must be called only once and before any calls to the other driver APIs.
Generally, this is done before SYS/BIOS is started.
—
The board files in the examples call this function for you.
•
Void Driver_Params_init(Driver_Params *params)
—
Initializes the driver’s parameter structure to default values. All drivers, with the exception of
GPIO, implement the Params structure. The Params structure is empty for some drivers.
•
Driver_Handle Driver_open(UInt index, Driver_Params *params)
—
Opens the driver instance specified by the index with the params provided.
—
If the params field is NULL, the driver uses default values. See specific drivers for their defaults.
—
Returns a handle that will be used by other driver APIs and should be saved.
—
If there is an error opening the driver or the driver has already been opened, Driver_open()
returns NULL.
•
Void Driver_close(Driver_Handle handle)
—
Closes the driver instance that was opened, specified by the driver handle returned during open.
—
Closes the driver immediately, without checking if the driver is currently in use. It is up to the
application to determine when to call Driver_close() and to ensure it doesn’t disrupt on-going
driver activity.
—
The Watchdog driver does not have a close() function, because the watchdog timer cannot be
disabled once it has been enabled.
* The GPIO driver implements only GPIO_init() to avoid complicating the driver. See Section 5.6 for
information on using the GPIO driver.
5.2.4 TI-RTOS Driver Implementations for Concerto Devices
If you are modifying the <board>.c file for an application, you will see types and data structures that are
defined by the lower-level driver implementations. These implementations are provided in the driver
directories. For example, the lower-level implementation for the I2C driver is in the
I2CTiva.c
and
I2CTiva.h
files in the
<tirtos_insall_dir>\packages\ti\drivers\i2c
directory.
The lower-level driver implementations for the TI-RTOS drivers on the M3 portion of Concerto devices
are as follows. (The .c file is listed, but the .h file contains important type definitions.)
•
EMAC:
EMACTiva.c
•
GPIO:
There is no lower-level implementation. The full implementation is in GPIO.c.
•
I2C:
I2CTiva.c
•
SDSPI:
SDSPITiva.c
•
SPI:
SPITivaDMA.c
•
UART:
UARTTiva.c
•
USBMSCHFatFs:
USBMSCHFatFsTiva.c
•
Watchdog:
WatchdogTiva.c
•
WiFi:
not available
42 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
Driver Framework www.ti.com
5.2.5 TI-RTOS Driver Implementations for TivaC Devices
If you are modifying the <board>.c file for an application, you will see types and data structures that are
defined by the lower-level driver implementations. These implementations are provided in the driver
directories. For example, the lower-level implementation for the I2C driver is in the
I2CTiva.c
and
I2CTiva.h
files in the
<tirtos_insall_dir>\packages\ti\drivers\i2c
directory.
The lower-level driver implementations for the TI-RTOS drivers on Tiva devices are as follows. (The .c
file is listed, but the .h file contains important type definitions.)
•
EMAC:
EMACSnow.c
•
GPIO:
There is no lower-level implementation. The full implementation is in GPIO.c.
•
I2C:
I2CTiva.c
•
SDSPI:
SDSPITiva.c
•
SPI:
SPITivaDMA.c
•
UART:
UARTTiva.c
•
USBMSCHFatFs:
USBMSCHFatFsTiva.c
•
Watchdog:
WatchdogTiva.c
•
WiFi:
WiFiTivaCC3000.c
5.2.6 TI-RTOS Driver Hwis for MSP430 Devices
For MSP430 devices, the SYS/BIOS kernel does not use a Hwi dispatcher to allow for run-time creation
of interrupts. For this reason, MSP430 users must create Hwis statically in the application's *.cfg file.
Follow the steps below to configure the appropriate Hwis for applications that use TI-RTOS drivers.
1. Identify the TI-RTOS drivers and implementations that you want to add into your application. TI-
RTOS has a set of MSP430 driver implementations to support the USCI and EUSCI peripherals.
Some TI-RTOS drivers (for example, WiFi) have dependencies on other TI-RTOS drivers.
2. Use Table 5-1 for MSP430F5xxx devices or Table 5-2 for MSP430FR5xxx devices to determine
whether these drivers require any Hwi interrupts to be created.
Table 5-1 SYS/BIOS Hwi functions required for TI-RTOS driver ISRs (USCI on MSP430F5xxx)
TI-RTOS Driver MSP430 Driver
Implementations Interrupt Service Routine Hwi Function Name
I
2
CI2CUSCIB I2CUSCIB_hwiIntFxn
SDSPI SDSPIUSCIA,
SDSPIUSCIB
N/A
This driver is polling based
SPI SPIUSCIADMA,
SPIUSCIBDMA
A DMA interrupt function defined by the user must call
the SPI driver's SPI_serviceISR function.
UART UARTUSCIA UARTUSCIA_hwiIntFxn
Watchdog WatchdogMSP430 N/A
This driver only generates a reset signal
WiFi WiFiMSP430CC3000 WiFiMSP430CC3000_hwiIntFxn and user DMA
interrupt function to call SPI_serviceISR (The WiFi
driver uses the SPI driver as a dependency)
SPRUHD4F—April 2014 TI-RTOS Drivers 43
Submit Documentation Feedback
www.ti.com Driver Framework
3. If the TI-RTOS driver is interrupt driven, find the peripheral's base address for every driver
implementation entry in the HWAttrs data structure of the driver’s Driver_config[] array.
For example, I2C_Config[0] has its HWAttrs data structure configured to USCI_B0_BASE. Similarly,
I2C_Config[1] has its HWAttrs data structure configured to use USBI_B1_BASE.
Table 5-2 SYS/BIOS Hwi functions required for TI-RTOS driver ISRs (EUSCI on MSP430FR5xxx)
TI-RTOS Driver MSP430 Driver
Implementations Interrupt Service Routine Hwi Function Name
I
2
CI2CEUSCIB I2CEUSCIB_hwiIntFxn
SDSPI SDSPIEUSCIA,
SDSPIEUSCIB
N/A
This driver is polling based
SPI SPIUSCIADMA,
SPIUSCIBDMA A DMA interrupt function defined by the user must call
the SPI driver's SPI_serviceISR function.
UART UARTEUSCIA UARTEUSCIA_hwiIntFxn
Watchdog WatchdogMSP430 N/A
This driver only generates a reset signal
WiFi WiFiMSP430CC3000 WiFiMSP430CC3000_hwiIntFxn and user DMA
interrupt function to call SPI_serviceISR (The WiFi
driver uses the SPI driver as a dependency)
/* I2C objects */
I2CUSCIB_Object i2cUSCIBObjects[MSP_EXP430F5529LP_I2CCOUNT];
/* I2C configuration structure */
const I2CUSCIB_HWAttrs i2cUSCIBHWAttrs[MSP_EXP430F5529LP_I2CCOUNT] = {
{
USCI_B0_BASE,
USCI_B_I2C_CLOCKSOURCE_SMCLK
},
{
USCI_B1_BASE,
USCI_B_I2C_CLOCKSOURCE_SMCLK
}
};
const I2C_Config I2C_config[] = {
{
&I2CUSCIB_fxnTable,
&i2cUSCIBObjects[0],
&i2cUSCIBHWAttrs[0]
},
{
&I2CUSCIB_fxnTable,
&i2cUSCIBObjects[1],
&i2cUSCIBHWAttrs[1]
},
{NULL, NULL, NULL}
};
44 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
Driver Framework www.ti.com
4. Find the associated interrupt vector number for each peripheral at the specified base address. For
example, on the MSP430F5529, the USBI_B0 interrupt vector is 55 and the USCI_B1 interrupt vector
is 45. The interrupt vector number is set in the device's main *.h header file. For MSP430F5529, the
file would be msp430f5529.h.
—
In CCS, this file is found in: <CCS_install>/ccsv6/ccs_base/msp430/include.
—
In IAR, this file is found in: <IAR_install>/430/inc.
5. Create Hwi objects for each entry in the Driver_config[] array using the information obtained in the
previous steps. Map the information to the Hwi in the following manner:
— Hwi (ISR) function.
Use the Hwi function name from Table 5-1.
— Interrupt vector number.
Use the vector number from the device's main *.h header file.
— Argument passed to ISR function.
Use the index number into the Driver_config[] array.
Hwi objects can be created using the graphical user interface or by manually adding it to the project’s
*.cfg file. Both of the following examples configure two Hwi objects that run the I2CUSCIB_hwiIntFxn
function required by the I
2
C driver with the interrupt vectors for USBI_B0 and USBI_B1.
This example shows the statements in the *.cfg file:
SPRUHD4F—April 2014 TI-RTOS Drivers 45
Submit Documentation Feedback
www.ti.com Driver Framework
This example shows how to configure the Hwi objects graphically with the XGCONF Configuration Editor:
46 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
EMAC Driver www.ti.com
5.3 EMAC Driver
This is the Ethernet driver used by the networking stack (NDK).
5.3.1 Static Configuration
To use the EMAC module, the application needs to include the EMAC module into the application’s
configuration file (.cfg). This can be accomplished textually:
var EMAC = xdc.useModule('ti.drivers.EMAC');
EMAC.libType = EMAC.LibType_Instrumented;
or graphically:
5.3.2 Runtime Configuration
As the overview in Section 5.2.2 indicates, the EMAC driver requires the application to initialize board-
specific portions of the EMAC and provide the EMAC driver with the EMAC_config structure.
5.3.2.1 Board-Specific Configuration
The <board>.c files contain a <board>_initEMAC() function that must be called to initialize the board-
specific EMAC peripheral settings. This function also calls the EMAC_init() to initialize the EMAC driver.
5.3.2.2 EMAC_config Structure
The <board>.c file also declare the EMAC_config structure. This structure must be provided to the EMAC
driver. It must be initialized before the EMAC_init() function is called and cannot be changed afterwards.
For details about the individual fields of this structure, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
. (The CDOC help available from within CCS
provides information about configuring the driver, but no information about the APIs.)
SPRUHD4F—April 2014 TI-RTOS Drivers 47
Submit Documentation Feedback
www.ti.com EMAC Driver
5.3.3 APIs
To use the EMAC module APIs, the EMAC header file should be included in an application as follows:
#include <ti/drivers/EMAC.h>
The following EMAC API is provided:
•
EMAC_init()
sets up the EMAC driver. This function must be called before the NDK stack thread is
started.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
(The CDOC help available from within CCS provides information about configuring the driver, but no
information about the APIs.)
See the NDK documentation for information about NDK APIs that can be used if the EMAC driver is
enabled and initialized.
5.3.4 Usage
The EMAC driver is designed to be used by the NDK. The only function that must be called is the
EMAC_init() function. This function must be called before BIOS_start() is called to ensure that the driver
is initialized before the NDK starts.
5.3.5 Instrumentation
The EMAC driver logs the following actions using the Log_print() APIs provided by SYS/BIOS.
•
EMAC driver setup success or failure.
•
EMAC started or stopped.
•
EMAC failed to receive or transmit a packet.
•
EMAC successfully sent or received a packet.
•
No packet could be allocated.
•
Packet is too small for the received buffer.
Logging is controlled by the Diags_USER1 and Diags_USER2 masks. Diags_USER1 is for general
information and Diags_USER2 is for more detailed information.
The EMAC driver provides the following ROV information through the EMAC module.
•
Basic parameters:
—
intVectId
—
macAddr
—
libType
•
Statistics:
—
rxCount
—
rxDropped
—
txSent
—
txDropped
5.3.6 Examples
See the TI-RTOS Getting Started Guide (SPRUHD3) for a list of examples that use the EMAC driver.
48 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
UART Driver www.ti.com
5.4 UART Driver
A UART is used to translate data between the chip and a serial port. The UART driver simplifies reading
and writing to any of the UART peripherals on the board with multiple modes of operation and
performance. These include blocking, non-blocking, and polling as well as text/binary mode, echo and
return characters.
5.4.1 Static Configuration
To use the UART driver, the application needs to include the UART module into the application’s
configuration file (.cfg). This can be accomplished textually:
var UART = xdc.useModule('ti.drivers.UART');
UART.libType = UART.LibType_Instrumented;
or graphically:
5.4.2 Runtime Configuration
As the overview in Section 5.2.2 indicates, the UART driver requires the application to initialize board-
specific portions of the UART and provide the UART driver with the UART_config structure.
5.4.2.1 Board-Specific Configuration
The <board>.c files contain a <board>_initUART() function that must be called to initialize the board-
specific UART peripheral settings. This function also calls the UART_init() to initialize the UART driver.
5.4.2.2 UART_config Structure
The <board>.c file also declare the UART_config structure. This structure must be provided to the UART
driver. It must be initialized before the UART_init() function is called and cannot be changed afterwards.
For details about the individual fields of this structure, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
. (The CDOC help available from within CCS
provides information about configuring the driver, but no information about the APIs.)
SPRUHD4F—April 2014 TI-RTOS Drivers 49
Submit Documentation Feedback
www.ti.com UART Driver
5.4.3 APIs
In order to use the UART module APIs, the UART header file should be included in an application as
follows:
#include <ti/drivers/UART.h>
The following are the UART APIs:
•
UART_init()
initializes the UART module.
•
UART_Params_init ()
initializes the UART_Params struct to its defaults for use in calls to
UART_open().
•
UART_open()
opens a UART instance.
•
UART_close()
closes a UART instance.
•
UART_write()
writes a buffer of characters to the UART.
•
UART_writePolling()
writes a buffer to the UART in the context of the call and returns when finished.
•
UART_writeCancel()
cancels the current write action and unblocks or make the callback.
•
UART_read()
reads a buffer of characters to the UART.
•
UART_readPolling()
reads a buffer to the UART in the context of the call and returns when finished.
•
UART_readCancel()
cancels the current read action and unblocks or make the callback.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
(The CDOC help available from within CCS provides information about configuring the driver, but no
information about the APIs.)
5.4.4 Usage
The UART driver does not configure any board peripherals or pins; this must be completed before any
calls to the UART driver. The examples call Board_initUART(), which is mapped to a specific initUART()
function for the board. The board-specific initUART() functions are provided in the board .c and .h files.
For example, a sample UART setup is provided in the TMDXDOCKH52C1_initUART() function in the
TMDXDOCKH52C1.c file. This function sets up the peripheral and pins used by UART0 for operation
through the JTAG emulation connection (no extra hardware needed). The examples that use the UART
driver call the Board_initUART() function from within main().
Once the peripherals are set up, the application must initialize the UART driver by calling UART_init(). If
you add the provided board setup files to your project, you can call the Board_initUART() function within
main().
Once the UART has been initialized, you can open UART instances. Only one UART index can be used
at a time. If the index is already in use, the driver returns NULL and logs a warning. Opening a UART
requires four steps:
1. Create and initialize a UART_Params structure.
2. Fill in the desired parameters.
3. Call UART_open() passing in the index of the UART from the configuration structure and Params.
4. Save the UART handle that is returned by UART_open(). This handle will be used to read and write
to the UART you just created.
50 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
UART Driver www.ti.com
For example:
UART_Handle uart;
UART_Params uartParams;
Board_initUART(); // Calls UART_init for you
/* Create a UART with data processing off. */
UART_Params_init(&uartParams);
uartParams.writeDataMode = UART_DATA_BINARY;
uartParams.readDataMode = UART_DATA_BINARY;
uartParams.readReturnMode = UART_RETURN_FULL;
uartParams.readEcho = UART_ECHO_OFF;
uart = UART_open(Board_UART, &uartParams);
Options for the writeMode and readMode parameters are UART_MODE_BLOCKING and
UART_MODE_CALLBACK.
•
UART_MODE_BLOCKING uses a semaphore to block while data is being sent. The context of the
call must be a SYS/BIOS Task.
•
UART_MODE_CALLBACK is non-blocking and will return while data is being sent in the context of
a Hwi. The UART driver will call the callback function whenever a write or read finishes. In some
cases, the action might have been canceled or received a newline, so the number of bytes
sent/received are passed in. Your implementation of the callback function can use this information as
needed.
Options for the writeDataMode and readDataMode parameters are UART_MODE_BINARY and
UART_MODE_TEXT. If the data mode is UART_MODE_BINARY, the data is passed as is, without
processing. If the data mode is UART_MODE_TEXT, write actions add a return before a newline
character, and read actions replace a return with a newline. This effectively treats all device line endings
as LF and all host PC line endings as CRLF.
Options for the readReturnMode parameter are UART_RETURN_FULL and
UART_RETURN_NEWLINE. These determine when a read action unblocks or returns. If the return
mode is UART_RETURN_FULL, the read action unblocks or returns when the buffer is full. If the return
mode is UART_RETURN_NEWLINE, the read action unblocks or returns when a newline character is
read.
Options for the readEcho parameter are UART_ECHO_OFF and UART_ECHO_ON. This parameter
determines whether the driver echoes data back to the UART. When echo is turned on, each character
that is read by the target is written back independent of any write operations. If data is received in the
middle of a write and echo is turned on, the characters echoed back will be mixed in with the write data.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
SPRUHD4F—April 2014 TI-RTOS Drivers 51
Submit Documentation Feedback
www.ti.com UART Driver
5.4.5 Instrumentation
The UART module provides instrumentation data both by making log calls and by sending data to the
ROV tool in CCS.
5.4.5.1 Logging
The UART driver is instrumented with Log events that can be viewed with UIA and RTOS Analyzer. Diags
masks can be turned on and off to provide granularity to the information that is logged.
Use Diags_USER1 to see general Log events such as success opening a UART, number of bytes read
or written, and warnings/errors during operation.
Use Diags_USER2 to see more granularity when debugging. Each character read or written will be
logged as well as several other key events.
The UART driver makes log calls when the following actions occur:
•
UART_open() success or failure
•
UART_close() success
•
UART interrupt triggered
•
UART_write() finished
•
Byte was written
•
UART_read() finished
•
Byte was read
•
UART_write() finished, canceled or timed out
•
UART_read() finished, canceled or timed out
5.4.5.2 ROV
The UART driver provides ROV information through the UART module. All UARTs that have been created
are displayed by their base address and show the following information:
•
Configuration parameters:
—
Base Address
—
Write Mode
—
Read Mode
—
Write Timeout
—
Read Timeout
—
Write Data Mode
—
Read Data Mode
—
Read Return mode
—
Read Echo
•
Write buffer: Contents of the write buffer
•
Read buffer: Contents of the read buffer
5.4.6 Examples
See the TI-RTOS Getting Started Guide (SPRUHD3) for a list of examples that use the UART driver.
52 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
I2C Driver www.ti.com
5.5 I
2
C Driver
This section assumes that you have background knowledge and understanding about how the I
2
C
protocol operates. For the full I
2
C specifications and user manual (UM10204), see the NXP
Semiconductors website.
The I
2
C driver has been designed to operate as a single I
2
C master by performing I
2
C transactions
between the target and I
2
C slave peripherals. The I
2
C driver does not support I
2
C slave mode at this time.
I
2
C is a communication protocol—the specifications define how data transactions are to occur via the I
2
C
bus. The specifications do not define how data is to be formatted or handled, allowing for flexible
implementations across different peripheral vendors. As a result, the I
2
C handles only the exchange of
data (or transactions) between master and slaves. It is the left to the application to interpret and
manipulate the contents of each specific I
2
C peripheral.
The I
2
C driver has been designed to operate in a RTOS environment such as SYS/BIOS. It protects its
transactions with OS primitives supplied by SYS/BIOS.
5.5.1 Static Configuration
To use the I
2
C driver, the application needs to include the I2C module into the application’s configuration
file (.cfg). This can be accomplished textually:
var I2C = xdc.useModule('ti.drivers.I2C');
I2C.libType = I2C.LibType_Instrumented;
or graphically:
5.5.2 Runtime Configuration
As the overview in Section 5.2.2 indicates, the I
2
C driver requires the application to initialize board-
specific portions of the I
2
C and provide the I
2
C driver with the I2C_config structure.
5.5.2.1 Board-Specific Configuration
The <board>.c files contain a <board>_initI2C() function that must be called to initialize the board-specific
I
2
C peripheral settings. This function also calls the I2C_init() to initialize the I
2
C driver.
SPRUHD4F—April 2014 TI-RTOS Drivers 53
Submit Documentation Feedback
www.ti.com I2C Driver
5.5.2.2 I2C_config Structure
The <board>.c file also declare the I2C_config structure. This structure must be provided to the I
2
C driver.
It must be initialized before the I2C_init() function is called and cannot be changed afterwards.
For details about the individual fields of this structure, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
. (The CDOC help available from within CCS
provides information about configuring the driver, but no information about the APIs.)
5.5.3 APIs
In order to use the I
2
C module APIs, the I2C.h header file should be included in an application as follows:
#include <ti/drivers/I2C.h>
The following are the I
2
C APIs:
•
I2C_init()
initializes the I
2
C module.
•
I2C_Params_init()
initializes an I2C_Params data structure. It defaults to Blocking mode.
•
I2C_open()
initializes a given I
2
C peripheral.
•
I2C_close()
deinitializes a given I
2
C peripheral.
•
I2C_transfer()
handles the I
2
C transfer for SYS/BIOS.
The I2C_transfer() API can be called only from a Task context. It requires an I2C_Tramsaction structure
that specifies the location of the write and read buffer, the number of bytes to be processed, and the I
2
C
slave address of the device.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
(The CDOC help available from within CCS provides information about configuring the driver, but no
information about the APIs.)
5.5.4 Usage
The application needs to supply the following structures in order to set up the framework for the driver:
•
I2C_Params
specifies the transfer mode and any callback function to be used. See Section 5.5.4.1.
•
I2C_Transaction
specifies details about a transfer to be performed. See Section 5.5.4.2.
•
I2C_Callback
specifies a function to be used if you are using callback mode. See Section 5.5.4.3.
5.5.4.1 I
2
C Parameters
The I2C_Params structure is used with the I2C_open() function call. If the transferMode is set to
I2C_MODE_BLOCKING, the transferCallback argument is ignored. If transferMode is set to
I2C_MODE_CALLBACK, a user-defined callback function must be supplied.
typedef struct I2C_Params {
I2C_TransferMode transferMode; /* Blocking or Callback mode */
I2C_CallbackFxn transferCallbackFxn; /* Callback function pointer */
} I2C_Params;
54 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
I2C Driver www.ti.com
5.5.4.2 I
2
C Transaction
The I2C_Transaction structure is used to specify what type of I2C_transfer needs to take place.
typedef struct I2C_Transaction {
UChar *writeBuf; /* Pointer to a buffer to be written */
UInt writeCount; /* Number of bytes to be written */
UChar *readBuf; /* Pointer to a buffer to be read */
UInt readCount; /* Number of bytes to be read */
UChar slaveAddress; /* Address of the I2C slave device */
UArg arg; /* User definable argument to the callback function */
Ptr nextPtr; /* Driver uses this for queuing in I2C_MODE_CALLBACK */
} I2C_Transaction;
slaveAddress specifies the I
2
C slave address the I
2
C will communicate with. If writeCount is nonzero,
I2C_transfer writes writeCount bytes from the buffer pointed by writeBuf. If readCount is nonzero,
I2C_transfer reads readCount bytes into the buffer pointed by readBuf. If both writeCount and readCount
are non-zero, the write operation always runs before the read operation.
The optional arg variable can only be used when the I
2
C driver has been opened in Callback mode. This
variable is used to pass a user-defined value into the user-defined callback function.
nextPtr is used to maintain a linked-list of I2C_Transactions when the I
2
C driver has been opened in
Callback mode. It must never be modified by the user application.
5.5.4.3 I
2
C Callback Function Prototype
This typedef defines the function prototype for the I
2
C driver’s callback function for Callback mode. When
the I
2
C driver calls this function, it supplies the associated I2C_Handle, a pointer to the I2C_Transaction
that just completed, and a Boolean value indicating the transfer result. The transfer result is the same as
from the I2C_transfer() when operating in Blocking mode.
typedef Void (*I2C_Callback)(I2C_Handle, I2C_Transaction *, Bool);
SPRUHD4F—April 2014 TI-RTOS Drivers 55
Submit Documentation Feedback
www.ti.com I2C Driver
5.5.5 I
2
C Modes
The I
2
C driver supports two modes of operation, blocking and callback modes. The mode is determined
when the I
2
C driver is opened using the I2C_Params data structure. If no I2C_Params structure is
specified, the I
2
C driver defaults to blocking mode. Once opened, the only way to change the operation
mode is to close and re-open the I
2
C instance with the new mode.
5.5.5.1 Opening in Blocking Mode
By default, the I
2
C driver operates in blocking mode. In blocking mode, a Task’s code execution is
blocked until an I
2
C transaction has completed. This ensures that only one I
2
C transaction operates at a
given time. Other tasks requesting I
2
C transactions while a transaction is currently taking place are also
placed into a blocked state and are executed in the order in which they were received.
I2C_Handle i2c;
UInt peripheralNum = 0; /* Such as I2C0 */
I2C_Params i2cParams;
I2C_Params_init(&i2cParams);
i2cParams.transferMode = I2C_MODE_BLOCKING;
i2cParams.transferCallbackFxn = NULL;
i2c = I2C_open(peripheralNum, &i2cParams);
if (i2c == NULL) {
/* Error opening I2C */
}
If no I2C_Params structure is passed to I2C_open(), default values are used. If the open call is
successful, it returns a non-NULL value.
5.5.5.2 Opening in Callback Mode
In callback mode, an I
2
C transaction functions asynchronously, which means that it does not block a
Task’s code execution. After an I
2
C transaction has been completed, the I
2
C driver calls a user-provided
hook function. If an I
2
C transaction is requested while a transaction is currently taking place, the new
transaction is placed onto a queue to be processed in the order in which it was received.
I2C_Handle i2c;
UInt peripheralNum = 0; /* Such as I2C0 */
I2C_Params i2cParams;
I2C_Params_init(&i2cParams);
i2cParams.transferMode = I2C_MODE_CALLBACK;
i2cParams.transferCallbackFxn = UserCallbackFxn;
i2c = I2C_open(peripheralNum, &i2cParams);
if (i2c == NULL) {
/* Error opening I2C */
}
56 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
I2C Driver www.ti.com
5.5.5.3 Specifying an I
2
C Bus Frequency
The I
2
C controller’s bus frequency is determined as part the I2C_Params data structure and is set when
the application calls I2C_open(). The standard I
2
C bus frequencies are 100 kHz and 400 kHz, with 100
kHz being the default.
I2C_Handle i2c;
UInt peripheralNum = 0; /* Such as I2C0 */
I2C_Params i2cParams;
I2C_Params_init(&i2cParams); /* Default is I2C_100kHz */
i2cParams.bitRate = I2C_400kHz;
i2c = I2C_open(peripheralNum, &i2cParams);
if (i2c == NULL) {
/* Error Initializing I2C */
}
5.5.6 I
2
C Transactions
I
2
C can perform three types of transactions: Write, Read, and Write/Read. All I
2
C transactions are atomic
operations with the slave peripheral. The I2C_transfer() function determines how many bytes need to be
written and/or read to the designated I
2
C peripheral by reading the contents of an I2C_Transaction data
structure.
The basic I2C_Transaction arguments include the slave peripheral’s I
2
C address, pointers to write and
read buffers, and their associated byte counters. The I
2
C driver always writes the contents from the write
buffer before it starts reading the specified number of bytes into the read buffer. If no data needs to be
written or read, simply set the corresponding counter(s) to 0.
5.5.6.1 Write Transaction (Blocking Mode)
As the name implies, an I
2
C write transaction writes data to a specified I
2
C slave peripheral. The following
code writes three bytes of data to a peripheral with a 7-bit slave address of 0x50.
I2C_Transaction i2cTransaction;
UChar writeBuffer[3];
UChar readBuffer[2];
Bool transferOK;
i2cTransaction.slaveAddress = 0x50; /* 7-bit peripheral slave address */
i2cTransaction.writeBuf = writeBuffer; /* Buffer to be written */
i2cTransaction.writeCount = 3; /* Number of bytes to be written */
i2cTransaction.readBuf = NULL; /* Buffer to be read */
i2cTransaction.readCount = 0; /* Number of bytes to be read */
transferOK = I2C_transfer(i2c, &i2cTransaction); /* Perform I2C transfer */
if (!transferOK) {
/* I2C bus fault */
}
SPRUHD4F—April 2014 TI-RTOS Drivers 57
Submit Documentation Feedback
www.ti.com I2C Driver
5.5.6.2 Read Transaction (Blocking Mode)
A read transaction reads data from a specified I
2
C slave peripheral. The following code reads two bytes
of data from a peripheral with a 7-bit slave address of 0x50.
I2C_Transaction i2cTransaction;
UChar writeBuffer[3];
UChar readBuffer[2];
Bool transferOK;
i2cTransaction.slaveAddress = 0x50; /* 7-bit peripheral slave address */
i2cTransaction.writeBuf = NULL; /* Buffer to be written */
i2cTransaction.writeCount = 0; /* Number of bytes to be written */
i2cTransaction.readBuf = readBuffer; /* Buffer to be read */
i2cTransaction.readCount = 2; /* Number of bytes to be read */
transferOK = I2C_transfer(i2c, &i2cTransaction); /* Perform I2C transfer */
if (!transferOK) {
/* I2C bus fault */
}
5.5.6.3 Write/Read Transaction (Blocking Mode)
A write/read transaction first writes data to the specified peripheral. It then writes an I
2
C restart bit, which
starts a read operation from the peripheral. This transaction is useful if the I
2
C peripheral has a pointer
register that needs to be adjusted prior to reading from referenced data registers. The following code
writes three bytes of data, sends a restart bit, and reads two bytes of data from a peripheral with the slave
address of 0x50.
I2C_Transaction i2cTransaction;
UChar writeBuffer[3];
UChar readBuffer[2];
Bool transferOK;
i2cTransaction.slaveAddress = 0x50; /* 7-bit peripheral slave address */
i2cTransaction.writeBuf = writeBuffer; /* Buffer to be written */
i2cTransaction.writeCount = 3; /* Number of bytes to be written */
i2cTransaction.readBuf = readBuffer; /* Buffer to be read */
i2cTransaction.readCount = 2; /* Number of bytes to be read */
transferOK = I2C_transfer(i2c, &i2cTransaction); /* Perform I2C transfer */
if (!transferOK) {
/* I2C bus fault */
}
5.5.6.4 Write/Read Transaction (Callback Mode)
In callback mode, I
2
C transfers are non-blocking transactions. After an I
2
C transaction has completed,
the I
2
C interrupt routine calls the user-provided callback function, which was passed in when the I
2
C
driver was opened.
58 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
I2C Driver www.ti.com
In addition to the standard I2C_Transaction arguments, an additional user-definable argument can be
passed through to the callback function.
I2C_Transaction i2cTransaction;
UChar writeBuffer[3];
UChar readBuffer[2];
Bool transferOK;
i2cTransaction.slaveAddress = 0x50; /* 7-bit peripheral slave address */
i2cTransaction.writeBuf = writeBuffer; /* Buffer to be written */
i2cTransaction.writeCount = 3; /* Number of bytes to be written */
i2cTransaction.readBuf = readBuffer; /* Buffer to be read */
i2cTransaction.readCount = 2; /* Number of bytes to be read */
i2cTransaction.arg = someOptionalArgument;
/* I2C_transfers will always return successful */
I2C_transfer(i2c, &i2cTransaction); /* Perform I2C transfer */
5.5.6.5 Queuing Multiple I
2
C Transactions
Using the callback mode, you can queue up multiple I
2
C transactions. However, each I
2
C transfer must
use a unique instance of an I2C_Transaction data structure. In other words, it is not possible to
reschedule an I2C_Transaction structure more than once. This also implies that the application must
make sure the I2C_Transaction isn’t reused until it knows that the I2C_Transaction is available again.
The following code posts a Semaphore after the last I2C_Transaction has completed. This is done by
passing the Semaphore’s handle through the I2C_Transaction data structure and evaluating it in the
UserCallbackFxn.
Void UserCallbackFxn(I2C_Handle handle, I2C_Transaction *msg, Bool transfer) {
if (msg->arg != NULL) {
Semaphore_post((Semaphore_Handle)(msg->arg));
}
}
Void taskfxn(arg0, arg1) {
I2C_Transaction i2cTransaction0;
I2C_Transaction i2cTransaction1;
I2C_Transaction i2cTransaction2;
/* Set up i2cTransaction0/1/2 here */
...
i2cTransaction0.arg = NULL;
i2cTransaction1.arg = NULL;
i2cTransaction2.arg = semaphoreHandle;
/* Start and queue up the I2C transactions */
I2C_transfer(i2c, &i2cTransaction0);
I2C_transfer(i2c, &i2cTransaction1);
I2C_transfer(i2c, &i2cTransaction2);
/* Do other optional code here */
...
/* Pend on the I2C transactions to have completed */
Semaphore_pend(semaphoreHandle);
}
SPRUHD4F—April 2014 TI-RTOS Drivers 59
Submit Documentation Feedback
www.ti.com I2C Driver
5.5.7 Instrumentation
The instrumented I
2
C library contains Log_print() statements that help to debug I
2
C transfers. The I
2
C
driver logs the following actions using the Log_print() APIs provided by SYS/BIOS:
•
I
2
C object opened or closed.
•
Data written or read in the interrupt handler.
•
Transfer results.
Logging is controlled by the Diags_USER1 and Diags_USER2 masks. Diags_USER1 is for general
information and Diags_USER2 is for more detailed information. Diags_USER2 provides detailed logs
intended to help determine where a problem may lie in the I
2
C transaction. This level of diagnostics will
generate a significant amount of Log entries. Use this mask when granular transfer details are needed.
The I
2
C driver provides ROV information through the I2C module. All I
2
Cs that have been created are
displayed by their base address and show the following information:
•
Basic parameters:
—
objectAddress: Address of the I
2
C object.
—
baseAddress: Base address of the peripheral being used.
—
mode: Current state of the I
2
C controller (Idle, Write, Read, or Error).
—
slaveAddress: The I
2
C address of the peripheral with which the I
2
C controller communicates.
5.5.8 Examples
See the TI-RTOS Getting Started Guide (SPRUHD3) for a list of examples that use the I
2
C driver.
60 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
GPIO Driver www.ti.com
5.6 GPIO Driver
The GPIO module allows you to manage General Purpose I/O pins and ports via simple and portable
APIs.
The application needs to supply a GPIO_Config structure to the module in order to allow the application
to call the GPIO_init(), GPIO_read(), GPIO_write(), and GPIO_toggle() APIs. To use the APIs to
configure GPIO interrupts, a GPIO_Callbacks structure for each port using interrupts must be supplied
as well.
After the GPIO_init() function is called, all managed pins are set up for output or input as needed.
Because of its simplicity, the GPIO driver does not follow the model of other TI-RTOS drivers in which a
driver application interface has separate device-specific implementations. This difference is most
apparent in the GPIO_config array (described in more detail in Section 5.6.2.2), which does not require
you to specify a particular function table or object.
5.6.1 Static Configuration
To use the GPIO driver, the application needs to include the GPIO module into the application’s
configuration file (.cfg). This can be accomplished textually:
var GPIO = xdc.useModule('ti.drivers.GPIO');
GPIO.libType = GPIO.LibType_Instrumented;
or graphically:
5.6.2 Runtime Configuration
As the overview in Section 5.2.2 indicates, the GPIO driver requires the application to initialize board-
specific portions of the GPIO and provide the GPIO driver with the GPIO_config structure.
5.6.2.1 Board-Specific Configuration
The <board>.c files contain a <board>_initGPIO() function that must be called to initialize the board-
specific GPIO peripheral settings. This function also calls the GPIO _init() to initialize the GPIO driver.
SPRUHD4F—April 2014 TI-RTOS Drivers 61
Submit Documentation Feedback
www.ti.com GPIO Driver
5.6.2.2 GPIO_config Structure
The <board>.c file also declare the GPIO_config structure. This structure must be provided to the GPIO
driver. It must be initialized before the GPIO_init() function is called and cannot be changed afterwards.
For details about the individual fields of this structure, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
. (The CDOC help available from within CCS
provides information about configuring the driver, but no information about the APIs.)
5.6.2.3 GPIO_Callbacks Structure
To use GPIO interrupts, the <board>.c file also needs to declare a structure of type const
GPIO_Callbacks for each port that contains one or more pins on which GPIO interrupts will be enabled.
These structures must then be passed to the GPIO_setupCallbacks() function before interrupts can be
enabled.
For details about this structure and its fields, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
5.6.3 APIs
In order to use the GPIO module APIs, the GPIO header file should be included in an application as
follows:
#include <ti/drivers/GPIO.h>
The following are the GPIO APIs:
•
GPIO_init()
sets up the configured GPIO ports and pins.
•
GPIO_read()
gets the current state of the specified GPIO pin.
•
GPIO_write()
sets the state of the specified GPIO pin to on or off.
•
GPIO_toggle()
toggles the state of the specified GPIO pin.
•
GPIO_setupCallbacks()
sets up the hardware interrupt and callback table for a GPIO port.
•
GPIO_clearInt()
clears the interrupt flag for the specified GPIO pin.
•
GPIO_disableInt()
disables interrupts on the specified GPIO pin.
•
GPIO_enableInt()
enables interrupts on the specified GPIO pin for the specified pin event.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
(The CDOC help available from within CCS provides information about configuring the GPIO driver, but
no information about the APIs.)
5.6.4 Usage
Once the GPIO_init() function has been called, the other GPIO APIs functions can be called. For
example, LEDs can be switched on as follows:
GPIO_write(Board_LED0, Board_LED_ON);
GPIO_write(Board_LED1, Board_LED_ON);
GPIO_write(Board_LED2, Board_LED_ON);
62 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
SPI Driver www.ti.com
For GPIO interrupts, once the GPIO_setupCallbacks() has been called for a port's GPIO_Callback
structure, that port may be enabled for interrupts as follows:
/* Init and enable interrupts */
GPIO_setupCallbacks(&Board_gpioCallbacks0)
GPIO_enableInt(Board_BUTTON0, GPIO_INT_FALLING);
GPIO_enableInt(Board_BUTTON1, GPIO_INT_RISING);
Interrupts may be configured to occur on rising edges, falling edges, both edges, a high level, or a low
level. When set as edge-triggered, the callback function must call GPIO_clearInt() to allow any further
interrupts to occur.
5.6.5 Instrumentation
The GPIO driver logs the following actions using the Log_print() APIs provided by SYS/BIOS:
•
GPIO pin read.
•
GPIO pin toggled.
•
GPIO pin written to.
•
GPIO hardware interrupt created.
•
GPIO interrupt flag cleared.
•
GPIO interrupt enabled.
•
GPIO interrupt disabled.
Logging is controlled by the Diags_USER1 and Diags_USER2 masks. Diags_USER1 is for general
information and Diags_USER2 is for more detailed information.
The GPIO driver provides ROV information through the GPIO module. All GPIOs that have been created
are displayed by their base address and show the following information:
•
Basic parameters:
—
baseAddress
—
pins
—
direction
—
value
5.6.6 Examples
All the TI-RTOS examples use the GPIO driver. The GPIO Interrupt example demonstrates interrupt
usage.
The GPIO_init() function is called in the board specific file (e.g. TMDXDOCKH52C1.c). A filled in
GPIO_Config structure is used in the same file.
5.7 SPI Driver
The Serial Peripheral Interface (SPI) driver is a generic, full-duplex driver that transmits and receives data
on a SPI bus. SPI is sometimes called SSI (Synchronous Serial Interface).
The SPI protocol defines the format of a data transfer over the SPI bus, but it leaves flow control, data
formatting, and handshaking mechanisms to higher-level software layers.
SPRUHD4F—April 2014 TI-RTOS Drivers 63
Submit Documentation Feedback
www.ti.com SPI Driver
5.7.1 Static Configuration
To use the SPI driver, the application needs to include the SPI module into the application's configuration
file (.cfg). This can be accomplished textually:
var SPI = xdc.useModule('ti.drivers.SPI');
SPI.libType = SPI.LibType_Instrumented;
Or graphically:
5.7.2 Runtime Configuration
As the overview in Section 5.2.2 indicates, the SPI driver requires the application to initialize board-
specific portions of the SPI and to provide the SPI driver with the SPI_config structure.
5.7.2.1 Board-Specific Configuration
The <board>.c files contain a <board>_initSPI() function that must be called to initialize the board-specific
SPI peripheral settings. This function also calls the SPI_init() to initialize the SPI driver.
5.7.2.2 SPI_config Structure
The <board>.c file also declares the SPI_config structure. This structure must be provided to the SPI
driver. It must be initialized before the SPI_init() function is called and cannot be changed afterwards.
For details about the individual fields of this structure, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
. (The CDOC help available from within CCS
provides information about configuring the driver, but no information about the APIs.)
5.7.3 APIs
In order to use the SPI module APIs, the SPI.h header file should be included in an application as follows:
#include <ti/drivers/SPI.h>
The following are the SPI APIs:
•
SPI_init()
initializes the SPI module.
64 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
SPI Driver www.ti.com
•
SPI_Params_init()
initializes a SPI_Params data structure to default values.
•
SPI_open()
initializes a given SPI peripheral.
•
SPI_close()
deinitializes a given SPI peripheral.
•
SPI_transfer()
handles the SPI transfers for SYS/BIOS.
The SPI_transfer() API can be called only from a Task context when used in SPI_MODE_BLOCKING. It
requires a SPI_Transaction structure that specifies the location of the write and read buffer and the
number of SPI frames to be transmitted/received. In SPI frame formats, data is sent in full-duplex mode.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
(The CDOC help available from within CCS provides information about configuring the driver, but no
information about the APIs.)
5.7.4 Usage
The application needs to supply the following structures in order to set up the framework for the driver:
•
SPI_Params
specifies the transfer mode and any callback function to be used. See Section 5.7.4.1.
•
SPI_Transaction
specifies details about a transfer to be performed. See Section 5.7.4.2.
•
SPI_Callback
specifies a function to be used if you are using callback mode. See Section 5.7.4.3.
5.7.4.1 SPI Parameters
The SPI_Params structure is used with the SPI_open() function call.
If the transferMode is set to SPI_MODE_BLOCKING, the transferCallback argument is ignored. If
transferMode is set to SPI_MODE_CALLBACK, a user-defined callback function must be supplied. The
mode parameter determines whether the SPI operates in master or slave mode. The desired SPI bit
transfer rate, frame data size, and frame format are specified with bitRate, dataSize and frameFormat
respectively.
typedef struct SPI_Params {
SPI_TransferMode transferMode; /* Blocking or Callback mode */
SPI_CallbackFxn transferCallbackFxn; /* Callback function pointer */
SPI_Mode mode; /* Master or Slave mode */
UInt bitRate; /* SPI bit rate in Hz */
UInt dataSize; /* SPI data frame size in bits */
SPI_FrameFormat frameFormat; /* SPI frame format */
} SPI_Params;
SPRUHD4F—April 2014 TI-RTOS Drivers 65
Submit Documentation Feedback
www.ti.com SPI Driver
5.7.4.2 SPI Frame Formats, Transactions, and Data Sizes
The SPI driver can configure the device's SPI peripheral with various SPI frameFormat options: SPI (with
various polarity and phase settings), TI, and Micro-wire.
The smallest single unit of data transmitted onto the SPI bus is called a SPI frame and is of size dataSize.
A series of SPI frames transmitted/received on a SPI bus is known as a SPI transaction. A SPI_transfer()
of a SPI transaction is performed atomically.
typedef struct SPI_Transaction {
UInt count; /* Number of frames for this transaction */
Ptr txBuf; /* Ptr to a buffer with data to be transmitted */
Ptr rxBuf; /* Ptr to a buffer to receive data */
UArg arg; /* Argument to be passed to the callback function */
} SPI_Transaction;
The txBuf and rxBuf parameters are both pointers to data buffers. If txBuf is NULL, the driver sends SPI
frames with all data bits set to 0. If rxBuf is NULL, the driver discards all SPI frames received.
When the SPI is opened, the dataSize value determines the element types of txBuf and rxBuf. If the
dataSize is from 4 to 8 bits, the driver assumes the data buffers are of type UChar (unsigned char). If the
dataSize is larger than 8 bits, the driver assumes the data buffers are of type UShort (unsigned short).
The optional arg variable can only be used when the SPI driver has been opened in callback mode. This
variable is used to pass a user-defined value into the user-defined callback function.
Specifics about SPI frame formatting and data sizes are provided in device-specific data sheets and
technical reference manuals.
5.7.4.3 SPI Callback Function Prototype
This typedef defines the function prototype for the SPI driver's callback function for callback mode:
typedef Void (*SPI_Callback)(SPI_Handle, SPI_Transaction *);
When the SPI driver calls this function, it supplies the associated SPI_Handle and a pointer to the
SPI_Transaction that just completed. There is no formal definition for what constitutes a successful SPI
transaction, so every callback is considered a successful transaction. The application or middleware
should examine the data to determine if the transaction met application-specific requirements.
5.7.5 Callback and Blocking Modes
The SPI driver supports two modes of operation: blocking and callback modes. The mode is determined
by the mode parameter in the SPI_Params data structure used when the SPI driver is opened. If no
SPI_Params structure is specified, the SPI driver defaults to blocking mode. Once a SPI driver is opened,
the only way to change the operation mode is to close and re-open the SPI instance with the new mode.
66 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
SPI Driver www.ti.com
5.7.5.1 Opening a SPI Driver in Blocking Mode
By default, the SPI driver operates in blocking mode. In blocking mode, a Task's code execution is
blocked until a SPI transaction has completed. This ensures that only one SPI transaction operates at a
given time. Other tasks requesting SPI transactions while a transaction is currently taking place are also
placed into a blocked state and are executed in the order in which they were received.
SPI_Handle spi;
UInt peripheralNum = 0; /* Such as SPI0 */
SPI_Params spiParams;
SPI_Params_init(&spiParams);
spiParams.transferMode = SPI_MODE_BLOCKING;
spiParams.transferCallbackFxn = NULL;
spi = SPI_open(peripheralNum, &spiParams);
if (spi == NULL) {
/* Error opening SPI */
}
Blocking mode is not supported in the execution context of a Swi or Hwi.
If no SPI_Params structure is passed to SPI_open(), default values are used. If the open call is
successful, it returns a non-NULL value.
5.7.5.2 Opening a SPI Driver in Callback Mode
In callback mode, a SPI transaction functions asynchronously, which means that it does not block code
execution. After a SPI transaction has been completed, the SPI driver calls a user-provided hook
function.
SPI_Handle spi;
UInt peripheralNum = 0; /* Such as SPI0 */
SPI_Params spiParams;
SPI_Params_init(&spiParams);
spiParams.transferMode = SPI_MODE_CALLBACK;
spiParams.transferCallbackFxn = UserCallbackFxn;
spi = SPI_open(peripheralNum, &spiParams);
if (spi == NULL) {
/* Error opening SPI */
}
Callback mode is supported in the execution context of Tasks, Swis and Hwis. However, if a SPI
transaction is requested while a transaction is taking place, the SPI_transfer() returns FALSE.
SPRUHD4F—April 2014 TI-RTOS Drivers 67
Submit Documentation Feedback
www.ti.com SPI Driver
5.7.6 SPI Transactions
SPI_transfer() always performs full-duplex SPI transactions. This means the SPI simultaneously receives
data as it transmits data. The application is responsible for formatting the data to be transmitted as well
as determining whether the data received is meaningful. The following code snippets perform SPI
transactions.
Transferring n 4-8 bit SPI frames:
SPI_Transaction spiTransaction;
UChar transmitBuffer[n];
UChar receiveBuffer[n];
Bool transferOK;
SPI_Params_init(&spiParams);
spiParams.dataSize = 6; /* dataSize can range from 4 to 8 bits */
spi = SPI_open(peripheralNum, &spiParams);
...
spiTransaction.count = n;
spiTransaction.txBuf = transmitBuffer;
spiTransaction.rxBuf = receiveBuffer;
transferOK = SPI_transfer(spi, &spiTransaction);
if (!transferOK) {
/* Error in SPI transfer or transfer is already in progress */
}
Transferring n 9-16 bit SPI frames:
SPI_Transaction spiTransaction;
UShort transmitBuffer[n];
UShort receiveBuffer[n];
Bool transferOK;
SPI_Params_init(&spiParams);
spiParams.dataSize = 12; /* dataSize can range from 9 to 16 bits */
spi = SPI_open(peripheralNum, &spiParams);
...
spiTransaction.count = n;
spiTransaction.txBuf = transmitBuffer;
spiTransaction.rxBuf = receiveBuffer;
transferOK = SPI_transfer(spi, &spiTransaction);
if (!transferOK) {
/* Error in SPI transfer or transfer is already in progress */
}
5.7.7 Master/Slave Modes
This SPI driver functions in both SPI master and SPI slave modes. Logically, the implementation is
identical; however the difference between these two modes is driven by hardware. As a SPI master, the
peripheral is in control of the clock signal and therefore will commence communications to the SPI slave
immediately. As a SPI slave, the SPI driver prepares the peripheral to transmit and receive data in a way
such that the peripheral is ready to transfer data when the SPI master initiates a transaction.
68 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
SPI Driver www.ti.com
Asserting on Chip Select
The SPI protocol requires that the SPI master asserts a SPI slave's chip select pin prior starting a SPI
transaction. While this protocol is generally followed, various types of SPI peripherals have different
timing requirements as to when and for how long the chip select pin must remain asserted for a SPI
transaction.
Commonly, the SPI master uses a hardware chip select to assert and de-assert the SPI slave for every
data frame. In other cases, a SPI slave imposes the requirement of asserting the chip select over several
SPI data frames. This is generally accomplished by using a regular, general-purpose output pin. Due to
the complexity of such SPI peripheral implementations, the SPI driver provided with TI-RTOS has been
designed to operate transparently to the SPI chip select. When the hardware chip select is used, the
peripheral automatically selects/enables the peripheral. When using a software chip select, the
application needs to handle the proper chip select and pin configuration.
•
Hardware chip select.
No additional action by the application is required.
•
Software chip select.
The application needs to handle the chip select assertion and de-assertion
for the proper SPI peripheral.
Note that the implementation of hardware chip select is device-dependent. MSP430 does not support the
hardware chip select feature. Tiva devices performs hardware chip select only when pin-muxed out.
5.7.8 Instrumentation
The instrumented SPI library contains Log_print() and Log_error() statements that help debug SPI
transfers. The SPI driver logs the following actions:
•
SPI object opened or closed
•
DMA transfer configurations enabled
•
SPI interrupt occurred
•
Initialization error occurred
•
Semaphore pend or post
Logging is controlled by the Diags_USER1 and Diags_USER2 masks. Diags_USER1 is for general
information and Diags_USER2 is for more detailed information. Diags_USER2 provides detailed logs
intended to help determine where a problem may lie in the SPI transactions. This level of diagnostics will
generate a significant amount of Log entries. Use this mask when granular transfer details are needed.
The SPI driver provides ROV information through the SPI module. All SPI instances are shown by the
address of the SPI handle.
•
Basic parameters:
—
SPI handle
—
base address
—
SPI function table
5.7.9 Examples
See the TI-RTOS Getting Started Guide (SPRUHD3) for a list of examples that use the SPI driver.
SPRUHD4F—April 2014 TI-RTOS Drivers 69
Submit Documentation Feedback
www.ti.com SPIMessageQTransport
5.8 SPIMessageQTransport
This MessageQ transport allows point to point communication over an SSI (Synchronous Serial
Interface) using the Serial Peripheral Interface (SPI) driver (see Section 5.7). It uses the MessageQ
modules, which is part of the Inter-Processor Communication (IPC) component.
To use this transport, there must be a master and slave processor. The master drives the SPI link. The
slave transport must be created and running before the master attempts to communicate to the master.
You can delay creation of the master by waiting to call SPIMessageQTransport_create() on the master
processor or using the clockStartDelay parameter when creating the transport instance.
5.8.1 Static Configuration
SPIMessageQTransport currently supports only dynamic creation of transport instances; you currently
cannot create a static transport instance in the .cfg file.
5.8.2 Runtime Configuration
The application must first initialize the SPI peripherals by calling <board>_initSPI() on both the master
and slave processors. This function performs pin-muxing and calls SPI_init() to initialize the driver.
After the SPI driver is initialized on both processors, the application should call
SPIMessageQTransport_create() on both processors to create an instance of the transport and open the
SPI drivers. For example, this code creates a SPIMessageQTransport instance:
/* Create the transport to the slave M3 */
SPIMessageQTransport_Params_init(&transportParams);
transportParams.maxMsgSize = BLOCKSIZE;
transportParams.heap = (IHeap_Handle)(heapHandle);
transportParams.spiIndex = 0;
transportParams.clockRate = 1;
transportParams.spiBitRate = 6000000;
transportParams.master = TRUE;
transportParams.priority = SPIMessageQTransport_Priority_NORMAL;
handle = SPIMessageQTransport_create(SLAVEM3PROCID, &transportParams, &eb);
if (handle == NULL) {
System_abort("SPIMessageQTransport_create failed\n");
}
The application also needs to set up a MessageQ instance to use the transport.
5.8.3 Error Conditions
During transport startup, the master and slave exchange a handshake. Any MessageQ_put() calls to the
remote processor fail until this handshake is completed.
Asynchronous errors can occur when using the transport. When one of these occur, the this transport
calls the any errFxn that was specified by the SPIMessageQTransport_setErrFxn() API. The following list
shows the errors that can occur and what information is passed in arguments to the errFxn.
•
Bad Msg.
The transport received a badly formed message.
—
Reason: SPIMessageQTransport_Reason_PHYSICALERR
—
Handle: Transport handle
—
Ptr: pointer to the received msg
—
UArg: SPIMessageQTransport_Failure_BADMSG
70 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
SPIMessageQTransport www.ti.com
•
Failed Checksum.
The transport received a message with a bad checksum.
—
Reason: SPIMessageQTransport_Reason_PHYSICALERR
—
Handle: Transport handle
—
Ptr: pointer to the received msg
—
UArg: SPIMessageQTransport_Failure_BADCHECKSUM
•
Allocation failure.
The allocation failed when the transport tried to copy incoming messages into an
allocated message.
—
Reason: SPIMessageQTransport_Reason_FAILEDALLOC
—
Handle: Transport handle
—
Ptr: NULL
—
UArg: heapId used to try to allocate the message
•
Failed transmit.
The transport failed to transmit a message.
—
Reason: SPIMessageQTransport_Reason_FAILEDPUT
—
Handle: Transport handle
—
Ptr: pointer to the msg that was not transmitted. The msg will be freed after the errFxn is called.
—
UArg: SPIMessageQTransport_Failure_TRANSFER
5.8.4 Examples
See the TI-RTOS Getting Started Guide (SPRUHD3) for information about the IPC SPI Master and IPC
SPI Slave examples that use SPIMessageQTransport.
SPRUHD4F—April 2014 TI-RTOS Drivers 71
Submit Documentation Feedback
www.ti.com SDSPI Driver
5.9 SDSPI Driver
The SDSPI FatFs driver is used to communicate with SD (Secure Digital) cards via SPI (Serial Peripheral
Interface).
The SDSPI driver is a FatFs driver module for the FatFs module provided in SYS/BIOS. With the
exception of the standard TI-RTOS driver APIs—SDSPI_open(), SDSPI_close(), and SDSPI_init()—the
SDSPI driver is exclusively used by FatFs module to handle the low-level hardware communications. See
Chapter 7, "Using the FatFs File System Drivers" for usage guidelines.
The SDSPI driver only supports one SSI (SPI) peripheral at a given time. It does not utilize interrupts.
The SDSPI driver is polling based for performance reasons and due the relatively high SPI bus bit rate.
This means it does not utilize the SPI’s peripheral interrupts, and it consumes the entire CPU time when
communicating with the SPI bus. Data transfers to or from the SD card are typically 512 bytes, which
could take a significant amount of time to complete. During this time, only higher priority Tasks, Swis, and
Hwis can preempt Tasks making calls that use the FatFs.
5.9.1 Static Configuration
To use the SDSPI driver, the application needs to include both the SYS/BIOS FatFS module and the
SDSPI module in the application’s configuration file (.cfg). This can be accomplished textually:
var FatFs = xdc.useModule('ti.sysbios.fatfs.FatFS');
var SDSPI = xdc.useModule('ti.drivers.SDSPI');
or graphically:
72 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
SDSPI Driver www.ti.com
5.9.2 Runtime Configuration
As the overview in Section 5.2.2 indicates, the SDSPI driver requires the application to initialize board-
specific portions of the SDSPI and provide the SDSPI driver with the SDSPI_config structure.
5.9.2.1 Board-Specific Configuration
The <board>.c files contain a <board>_initSDSPI() function that must be called to initialize the board-
specific SDSPI peripheral settings. This function also calls the SDSPI_init() to initialize the SDSPI driver.
5.9.2.2 SDSPI_config Structure
The <board>.c file also declare the SDSPI_config structure. This structure must be provided to the
SDSPI driver. It must be initialized before the SDSPI_init() function is called and cannot be changed
afterwards.
For details about the individual fields of this structure, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
. (The CDOC help available from within CCS
provides information about configuring the driver, but no information about the APIs.)
5.9.3 APIs
In order to use the SDSPI module APIs, include the SDSPI header file in an application as follows:
#include <ti/drivers/SDSPI.h>
The following are the SDSPI APIs:
•
SDSPI_init()
sets up the specified SPI and GPIO pins for operation.
•
SDSPI_open()
registers the SDSPI driver with FatFs and mounts the FatFs file system.
•
SDSPI_close()
unmounts the file system and unregisters the SDSPI driver from FatFs.
•
SDSPI_Params_init()
initializes a SDSPI_Params structure to its defaults.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
(The CDOC help provides information about configuring the driver, but no information about the APIs.)
5.9.4 Usage
Before any FatFs or C I/O APIs can be used, the application needs to open the SDSPI driver. The
SDSPI_open() function ensures that the SDSPI disk functions get registered with the FatFs module that
subsequently mounts the FatFs volume to that particular drive.
SDSPI_Handle sdspiHandle;
SDSPI_Params sdspiParams;
UInt peripheralNum = 0; /* Such as SPI0 */
UInt FatFsDriveNum = 0;
SDSPI_Params_init(&sdspiParams);
sdspiHandle = SDSPI_open(peripheralNum, FatFsDriveNum, &sdspiParams);
if (sdspiHandle == NULL) {
System_abort("Error opening SDSPI\n");
}
Similarly, the SDSPI_close() function unmounts the FatFs volume and unregisters SDSPI disk functions.
SDSPI_close(sdspiHandle);
SPRUHD4F—April 2014 TI-RTOS Drivers 73
Submit Documentation Feedback
www.ti.com SDSPI Driver
Note that it is up to the application to ensure the no FatFs or C I/O APIs are called before the SDSPI
driver has been opened or after the SDSPI driver has been closed.
5.9.5 Instrumentation
The SDSPI driver does not make any Log calls.
The SDSPI driver provides the following information to the ROV tool through the SDSPI module.
•
Basic parameters:
— baseAddress.
Base address of the peripheral being used to access the SD card.
— CardType.
The SD card type detected during the disk initialization phase. The card type can be
Multi-media Memory Card (MMC), Standard SDCard (SDSC), High Capacity SDCard (SDHC),
or NOCARD for an unrecognized card.
— diskState.
Current status of the SD card.
5.9.6 Examples
See the TI-RTOS Getting Started Guide (SPRUHD3) for a list of examples that use the SDSPI driver.
74 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
USBMSCHFatFs Driver www.ti.com
5.10 USBMSCHFatFs Driver
The USBMSCHFatFs driver is a FatFs driver module that has been designed to be used by the FatFs
module that comes with SYS/BIOS. With the exception of the standard TI-RTOS driver APIs—_open(),
_close(), and _init()—the USBMSCHFatFs driver is exclusively used by FatFs module to handle
communications to a USB flash drive. See Chapter 7 for usage guidelines.
The USBMSCHFatFs driver is uses the USB Library, which is provided with TivaWare and MWare to
communicate with USB flash drives as a USB Mass Storage Class (MSC) host controller. Only one USB
flash drive connected directly to the USB controller at a time is supported.
Tasks that make FatFs calls can be preempted only by higher priority tasks, Swis, and Hwis.
5.10.1 Static Configuration
To use the USB driver, the application needs to include the USBMSCHFatFs and FatFS modules into the
application’s configuration file (.cfg). This can be accomplished textually:
var FatFs = xdc.useModule('ti.sysbios.fatfs.FatFS');
var USBMSCHFatFs = xdc.useModule('ti.drivers.USBMSCHFatFs');
or graphically:
5.10.2 Runtime Configuration
As the overview in Section 5.2.2 indicates, the USBMSCHFatFs driver requires the application to initialize
board-specific portions of the USBMSCHFatFs and provide the USBMSCHFatFs driver with the
USBMSCHFatFs_config structure.
5.10.2.1 Board-Specific Configuration
The <board>.c files contain a <board>_initUSBMSCHFatFs() function that must be called to initialize the
board-specific USBMSCHFatFs peripheral settings. This function also calls the USBMSCHFatFs_init()
to initialize the USBMSCHFatFs driver.
SPRUHD4F—April 2014 TI-RTOS Drivers 75
Submit Documentation Feedback
www.ti.com USBMSCHFatFs Driver
5.10.2.2 USBMSCHFatFs_config Structure
The <board>.c file also declare the USBMSCHFatFs_config structure. This structure must be provided
to the USBMSCHFatFs driver. It must be initialized before the USBMSCHFatFs_init() function is called
and cannot be changed afterwards.
For details about the individual fields of this structure, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
. (The CDOC help available from within CCS
provides information about configuring the driver, but no information about the APIs.)
5.10.3 APIs
In order to use the USBMSCHFatFs module APIs, the USBMSCHFatFs header file should be included
in an application as follows:
#include <ti/drivers/USBMSCHFatFs.h>
The following are the USBMSCHFatFs APIs:
•
USBMSCHFatFs_init()
initializes the USBMSCHFatFs data objects pointed by the driver’s config
structure.
•
USBMSCHFatFs_open()
registers the USBMSCHFatFs driver with FatFs and mounts the FatFs file
system.
•
USBMSCHFatFs_close()
unmounts the file system and unregisters the USBMSCHFatFs driver
from FatFs.
•
USBMSCHFatFs_Params_init()
initializes a USBMSCHFatFs_Params structure to its defaults.
•
USBMSCHFatFs_waitForConnect()
blocks a task’s execution until a USB flash drive was detected.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
(The CDOC help available from within CCS provides information about configuring the driver, but no
information about the APIs.)
5.10.4 Usage
Before the FatFs APIs can be used, the application needs to open the USBMSCHFatFs driver. The
USBMSCHFatFs_open() function ensures that the USBMSCHFatFs disk functions get registered with
the FatFs module. The FatFs module then mounts the FatFs volume to that particular drive.
Internally, opening the USBMSCHFatFs driver creates a high-priority Task to service the USB library. The
default priority for this task is 15 and runs every 10 SYS/BIOS system ticks. You can change the priority
of this task using the USBMSCHFatFs_Params structure.
USBMSCHFatFs_Handle usbmschfatfsHandle;
USBMSCHFatFs_Params usbmschfatfsParams;
UInt peripheralNum = 0; /* Such as USB0 */
UInt FatFsDriveNum = 0;
USBMSCHFatFs_Params_init(&usbmschfatfsParams);
usbmschfatfsHandle =
USBMSCHFatFs_open(peripheralNum, FatFsDriveNum, &usbmschfatfsParams);
if (usbmschfatfsHandle == NULL) {
System_abort("Error opening USBMSCHFatFs\n");
}
76 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
USBMSCHFatFs Driver www.ti.com
Similarly, the close() function unmounts the FatFs volume and unregisters the USBMSCHFatFs disk
functions.
USBMSCHFatFs_close(usbmschfatfsHandle);
The application must ensure the no FatFs or C I/O APIs are called before the USBMSCHFatFs driver has
been opened or after the USBMSCHFatFs driver has been closed.
Although the USBMSCHFatFs driver may have been opened, there is a possibility that a USB flash drive
may not be present. To ensure that a Task will wait for a USB drive to be present, the USBMSCHFatFs
driver provides the USBMSCHFatFs_waitForConnect() function to block the Task’s execution until a USB
flash drive is detected.
5.10.5 Instrumentation
The USBMSCHFatFs driver logs the following actions using the Log_print() APIs provided by SYS/BIOS:
•
USB MSC device connected or disconnected.
•
USB drive initialized.
•
USB drive read or failed to read.
•
USB drive written to or failed to write.
•
USB status OK or error.
Logging is controlled by the Diags_USER1 and Diags_USER2 masks. Diags_USER1 is for general
information and Diags_USER2 is for more detailed information.
The USBMSCHFatFs driver does not provide any information to the ROV tool.
5.10.6 Examples
See the TI-RTOS Getting Started Guide (SPRUHD3) for a list of examples that use the USBMSCHFatFs
driver.
SPRUHD4F—April 2014 TI-RTOS Drivers 77
Submit Documentation Feedback
www.ti.com USB Reference Modules
5.11 USB Reference Modules
This section provides general guidelines for integrating TI’s USB Library into an RTOS environment such
as SYS/BIOS. The USB Library incorporated with TI-RTOS is a released version of TivaWare’s, MWare’s
or MSP430Ware’s USB library. This document does not explain each Ware’s USB Library in detail.
Instead, it points out important design considerations to consider in application development.
The USB library is highly customizable, and it uses its associated driverlib software to access physical
registers on the device, in particular those of the USB controller. To avoid limiting its capabilities by
providing a driver that uses the library in a particular way, the TI-RTOS USB examples are structured as
reference modules with the expectation that the developer makes the necessary changes for production.
Reference modules are examples that give developers full access, so they can make changes and
modifications as needed. The goal of these modules is to provide a starting point for integrating the USB
library into a SYS/BIOS application.
78 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
USB Reference Modules www.ti.com
5.11.1 USB Reference Modules in TI-RTOS
Each module handles the following items:
•
Initializes the USB library and provides the necessary memory allocation, data structures, and
callback functions.
•
Installs the associated USB interrupt service routine provided with the USB library as a SYS/BIOS
HWI object.
—
For MSP430 devices, interrupts are installed via the configuration file (*.cfg). The interrupt
service routine was generated using the MSP430 USB Descriptor Tool.
•
Provides a set of thread-safe APIs that can be used by one or more SYS/BIOS Tasks.
•
Creates the necessary RTOS primitives to protect critical regions and allows Tasks to block when
possible.
•
For USB Host examples, it also creates separate Task that services the USB stack.
5.11.1.1 Reference module APIs
All of the reference modules include the following APIs. Each module also includes specific APIs unique
to that particular module.
•
Module_init()
– This function initializes the USB library, creates RTOS primitives, and installs the
proper interrupt handler. For the host examples, it also creates a Task to service the USB controller.
•
Module_waitForConnect()
– This function causes a Task to block when the USB controller is not
connected.
5.11.1.2 USB Examples
TI-RTOS has six USB reference examples and one USB FatFs (MSC host) driver. (On-the-go (OTG)
examples are not available with TI-RTOS.) The reference examples and driver are as follows:
•
HID Host Keyboard
– Allows a USB keyboard to be connected to the target. Keys pressed on the
keyboard are registered on the target.
•
HID Host Mouse
– Allows a USB mouse to be connected to the target. The target registers the
overall mouse movements and button presses.
•
HID Device Keyboard
– Causes the target to emulate a USB keyboard. When connected to a
workstation, the target functions as another USB keyboard.
•
HID Device Mouse
– Causes the target to emulate a USB mouse when connected to a workstation.
•
CDC Device (Serial)
– The target enumerates a virtual serial COM port on a workstation. This
method of communication is commonly used to replace older RS-232 serial adapters.
•
HID Mouse and CDC composite device
– This example enumerates two different USB devices—
a HID mouse and a CDC serial virtual COM port.
•
MSC Host
(Mass Storage) – This example uses an actual driver instead of a USB reference module.
This driver is modeled after the FatFs driver APIs. This driver allows external mass storage devices
such a USB flash drives to be used with FatFs.
SPRUHD4F—April 2014 TI-RTOS Drivers 79
Submit Documentation Feedback
www.ti.com USB Reference Modules
5.11.1.3 USB Reference Modules for MSP430
The USB reference modules for MSP430 devices closely follow the USB examples available in
MSP430Ware. Here are a few items to note:
•
Since USB reference modules for MSP430 are imported via TI Resource Explorer, a full copy of the
MSP430Ware's usblib430 USB stack and a set of pre-generated USB descriptor files are copied into
the CCS project.
•
The generated USB descriptor files are considered user code. These descriptor files have been
tested to work with this version of TI-RTOS. Refer to the MSP430Ware USB documentation if you
are generating custom USB descriptors using the USB Descriptor Tool.
•
The UsbIsr.c file, which is generated by the USB Descriptor Tool, contains the interrupt service
routine needed by MSP430Ware's usblib430 library. The TI-RTOS USB reference module examples
use this interrupt service routine through configuration in the project’s *.cfg file.
5.11.2 USB Reference Module Design Guidelines
This section discusses the structure of the USB reference examples.
Design considerations involved in creating these examples included:
•
USB Device Specifics.
Each module contains memory, data structures, and a callback function
needed to function properly with the USB library. In device mode, the reference module also includes
device descriptors that need to be sent to the USB host controller upon request.
•
OS Primitives.
OS primitives that implement gates, mutexes, and semaphores are used to guard
data against race-conditions and reduce unwanted processing time by blocking Tasks when needed.
•
Memory Allocation.
The USB library is designed so that the user application performs all required
memory allocation. In a multi-tasked / preempted environment such as SYS/BIOS, it is necessary to
protect this memory from other threads. In the reference examples, this is done using the GateMutex
module.
•
Callback Functions.
The USB library requires user-provided callback functions to notify the
application of events. The USB reference modules provide a set of callback functions to notify the
module of status updates. The callback functions update an internal state variable and in some cases
post Semaphores to unblock pending Tasks.
•
Interrupts.
Some of the events that trigger callback functions are hardware notifications about the
device being connected or disconnected from a USB host controller.
5.11.2.1 Device Mode
USB Device mode examples are rather straightforward. In device mode, the job of the USB library is to
respond to the USB host controller with its current state/status. By making USB library API calls in device
mode, the example updates information stored in the USB controller’s endpoints. This information can
be queried by the USB host controller.
5.11.2.2 Host Mode
All USB Host mode examples install a high-priority Task to service the USB controller. This Task calls the
USB library's HCDMain() function, which maintains the USB library's internal state machine. This state
machine performs actions that include enumerating devices and performing callbacks as described in the
Tiva USB library documentation.
80 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
USB Device and Host Modules www.ti.com
To protect the USB library from race conditions between the service Task and other Tasks making calls
to the module’s APIs, a GateMutex is used.
5.11.2.3 On-The-Go Mode
OTG is not currently used by a USB reference module.
5.12 USB Device and Host Modules
See the USB examples for reference modules that provide support for the Human Interface Device (HID)
class (mouse and keyboard) and the Communications Device Class (CDC). This code is provided as part
of the examples, not as a separate driver.
The code for the HID keyboard device is in USBKBD.c in the USB Keyboard Device example. This file
provides the following functions:
•
USBKBD_init()
•
USBKBD_waitForConnect()
•
USBKBD_getState()
•
USBKBD_putChar()
•
USBKBD_putString()
The code for the HID keyboard host is in USBKBH.c in the USB Keyboard Host example. This file
provides the following functions:
•
USBKBH_init()
•
USBKBH_waitForConnect()
•
USBKBH_getState()
•
USBKBH_setState()
•
USBKBH_putChar()
•
USBKBH_putString()
The code for the HID mouse device is in USBMD.c in the USB Mouse Device example. This file provides
the following functions:
•
USBMD_init()
•
USBMD_waitForConnect()
•
USBMD_setState()
The code for the HID mouse host is in USBMH.c in the USB Mouse Host example. This file provides the
following functions:
•
USBMH_init()
•
USBMH_waitForConnect()
•
USBMH_getState()
SPRUHD4F—April 2014 TI-RTOS Drivers 81
Submit Documentation Feedback
www.ti.com Watchdog Driver
The code for the CDC device is in USBCDCD.c in the F28M3x Demo example, the USB Serial Device
example, and the UART Console example. This file provides the following functions:
•
USBCDCD_init()
•
USBCDCD_waitForConnect()
•
USBCDCD_sendData()
•
USBCDCD_receiveData()
The code for the CDC mouse is in USBCDCMOUSE.c in the USB CDC Mouse Device example. This file
provides the following functions:
•
USBCDCMOUSE_init()
•
USBCDCMOUSE_receiveData()
•
USBCDCMOUSE_sendData()
•
USBCDCMOUSE_waitForConnect()
5.13 Watchdog Driver
A watchdog timer can be used to generate a reset signal if a system has become unresponsive. The
Watchdog driver simplifies configuring and starting the watchdog peripherals. The watchdog peripheral
can be configured with resets either on or off and a user-specified timeout period.
When the watchdog peripheral is configured not to generate a reset, it can be used to cause a hardware
interrupt at a programmable interval. The driver provides the ability to specify a user-provided callback
function that is called when the watchdog causes an interrupt.
5.13.1 Static Configuration
To use the Watchdog driver, the application needs to include the Watchdog module into the application’s
configuration file (.cfg). This can be accomplished textually:
var Watchdog = xdc.useModule('ti.drivers.Watchdog');
82 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
Watchdog Driver www.ti.com
or graphically:
5.13.2 Runtime Configuration
As the overview in Section 5.2.2 indicates, the Watchdog driver requires the application to initialize
board-specific portions of the watchdog and to provide the Watchdog driver with the Watchdog_config
structure.
5.13.2.1 Board-Specific Configuration
The <board>.c files contain a <board>_initWatchdog() function that must be called to initialize the board-
specific watchdog peripheral settings. This function also calls the Watchdog_init() to initialize the
Watchdog driver.
5.13.2.2 Watchdog_config Structure
The <board>.c file also declares the Watchdog_config structure. This structure must be provided to the
Watchdog driver. It must be initialized before the Watchdog_init() function is called and cannot be
changed afterwards.
For details about the individual fields of this structure, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
. (The CDOC help available from within CCS
provides information about configuring the driver, but no information about the APIs.)
5.13.3 APIs
In order to use the Watchdog module APIs, the Watchdog header file should be included in an application
as follows:
#include <ti/drivers/Watchdog.h>
The following are the Watchdog APIs:
•
Watchdog_init()
initializes the Watchdog module.
•
Watchdog_Params_init()
initializes the Watchdog_Params struct to its defaults for use in calls to
Watchdog_open().
SPRUHD4F—April 2014 TI-RTOS Drivers 83
Submit Documentation Feedback
www.ti.com Watchdog Driver
•
Watchdog_open()
opens a Watchdog instance.
•
Watchdog_clear()
clears the Watchdog interrupt flag.
•
Watchdog_setReload()
sets the Watchdog reload value.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
(The CDOC help available from within CCS provides information about configuring the driver, but no
information about the APIs.)
5.13.4 Usage
The Watchdog driver does not configure board peripherals. This must be done before any calls to the
Watchdog driver. The examples include board-specific initWatchdog() functions in the board .c and .h
files. Once the watchdog is initialized, a Watchdog object can be created through the following steps:
1. Create and initialize the Watchdog_Params structure.
2. Assign desired values to parameters.
3. Call Watchdog_open().
4. Save the Watchdog_Handle returned by Watchdog_open(). This will be used to interact with the
Watchdog object just created.
To have a user-defined function run at the hardware interrupt caused by a watchdog timer timeout, define
a Void-type function that takes an argument of type Watchdog_Handle cast as a UArg as follows:
typedef Void (*Watchdog_Callback)(UArg);
An example of the Watchdog creation process that uses a callback function:
Watchdog_Params params;
Watchdog_Handle watchdog;
Board_initWatchdog();
/* Create and enable a Watchdog with resets enabled */
Watchdog_Params_init(&params);
params.resetMode = Watchdog_RESET_ON;
params.callbackFxn = UserCallbackFxn;
watchdog = Watchdog_open(Board_WATCHDOG, &params);
if (watchdog == NULL) {
/* Error opening watchdog */
}
If no Watchdog_Params structure is passed to Watchdog_open(), the default values are used. By default,
the Watchdog driver has resets turned on, no callback function specified, and stalls the timer at
breakpoints during debugging.
Options for the resetMode parameter are Watchdog_RESET_ON and Watchdog_RESET_OFF. The
latter allows the watchdog to be used like another timer interrupt. When resetMode is
Watchdog_RESET_ON, it is up to the application to call Watchdog_clear() to clear the Watchdog
interrupt flag to prevent a reset. Watchdog_clear() can be called at any time.
5.13.5 Instrumentation
The Watchdog module provides instrumentation data by both making log calls and by sending data to the
ROV tool in CCS.
84 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
WiFi Driver www.ti.com
The Watchdog driver logs the following actions using the Log_print() APIs provided by SYS/BIOS.
•
Watchdog_open() success or failure
•
Reload value changed
In the ROV tool, all Watchdogs that have been created are displayed and show the following information.
•
Basic parameters:
—
Watchdog handle
—
base address
—
Watchdog function table
5.13.6 Examples
See the TI-RTOS Getting Started Guide (SPRUHD3) for a list of examples that use the Watchdog driver.
5.14 WiFi Driver
The TI-RTOS WiFi driver implements many elements needed to communicate with a TI Wi-Fi device such
as the SimpleLink Wi-Fi CC3000. The WiFi driver uses the TI-RTOS SPI module and implements a state
machine to send and receive commands, data, and events to and from a Wi-Fi device.
This driver’s APIs let you open a WiFi driver instance to communicate with the Wi-Fi device's host driver
without further direct calls to the WiFi driver from the application. TI-RTOS provides host drivers for its
supported Wi-Fi devices in
<tirtos_install>\packages\ti\drivers\wifi\<wi-fi_device_name>
.
You can configure the driver to allow calling the WiFi driver from a single thread or to be safe to call from
multiple threads. The multi-threaded version of host driver consumes more resources than the single-
thread version. The WiFi driver supports only one instance of the driver.
For details on which resources each implementation of the WiFi driver uses (such as DMA channels and
interrupts), see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
SPRUHD4F—April 2014 TI-RTOS Drivers 85
Submit Documentation Feedback
www.ti.com WiFi Driver
5.14.1 Static Configuration
To use the WiFi driver, the application needs to include the WiFi module into the application's
configuration file (.cfg). This can be accomplished textually:
var WiFi = xdc.useModule('ti.drivers.WiFi');
or graphically:
By default, the WiFi library linked into the project is prebuilt with a version of the WiFi device's host driver
that is only safe to call from a single task. You can choose to allow calling the WiFi driver from multiple
threads. The multi-threaded version of host driver consumes more resources than the single-thread
version.
If you choose the multi-threaded version, internal calls by the WiFi host driver are run from within a Task
thread called SelectThread in order to allow other host driver API calls to run while the WiFi driver is
waiting for a response. You can configure the priority of the SelectThread task; the default priority is 1,
which is just above the priority of the Idle thread.
86 TI-RTOS Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
WiFi Driver www.ti.com
In addition to library type, the WiFi driver requires the maximum TX and RX data payload sizes to be
configured statically. These payload sizes are used by the WiFi module to create appropriately-sized
buffers for use by the WiFi driver and Wi-Fi device's host driver. They can be specified graphically as
shown in the previous image or textually as follows:
WiFi.txPayloadSize = 1468;
WiFi.rxPayloadSize = 1468;
In order to use the WiFi driver, your configuration must also include the SPI module. See Section 5.7, SPI
Driver for details.
5.14.2 Runtime Configuration
As the overview in Section 5.2.2 indicates, the WiFi driver requires the application to initialize board-
specific portions of the WiFi driver and provide the WiFi driver with the WiFi _config structure. A
SPI_config structure is also required by the WiFi driver.
5.14.2.1 Board-Specific Configuration
The <board>.c files contain a <board>_initWiFi() function that must be called to initialize the board-
specific WiFi peripheral settings. This function also calls WiFi_init() and SPI_init() to initialize the WiFi
driver and its resources.
5.14.2.2 WiFi_config Structure
The <board>.c file also declares the WiFi_config structure. This structure must be provided to the WiFi
driver. It must be initialized before the WiFi_init() function is called and cannot be changed afterwards.
For details about the individual fields of this structure, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
. (The CDOC help available from within CCS
provides information about configuring the driver, but no information about the APIs.)
Note that the SPI_config structure must also be present and initialized before the WiFi driver may be
used. See Section 5.7, SPI Driver for details.
5.14.3 APIs
In order to use the WiFi module APIs, the WiFi header file should be included in an application as follows:
#include <ti/drivers/WiFi.h>
The following are the WiFi APIs:
•
WiFi_init()
initializes the WiFi module.
•
WiFi_Params_init()
initializes the WiFi_Params struct to its defaults for use in calls to WiFi_open().
•
WiFi_open()
opens a WiFi instance.
•
WiFi_close()
closes a WiFi instance.
For details, see the Doxygen help by opening
<tirtos_install>\docs\doxygen\html\index.html
.
(The CDOC help available from within CCS provides information about configuring the driver, but no
information about the APIs.)
SPRUHD4F—April 2014 TI-RTOS Drivers 87
Submit Documentation Feedback
www.ti.com WiFi Driver
5.14.4 Usage
Before any APIs from the Wi-Fi device's host driver can be used, the application must open the WiFi
driver. The WiFi_open() function configures the SPI driver, creates necessary interrupts, and registers a
callback to inform the application of events that may occur on the Wi-Fi device. Once WiFi_open() has
returned, host driver APIs may be used to start sending commands and data to the Wi-Fi device.
WiFi_Params params;
WiFi_Handle handle;
/* Open WiFi */
WiFi_Params_init(&params);
params.bitRate = 5000000; /* Set bit rate to 5 MHz */
handle = WiFi_open(Board_wifiIndex, Board_spiIndex, userCallback, &params);
if (handle == NULL) {
System_abort("Error opening WiFi\n");
}
/* Host driver APIs such as socket() may now be called. */
The WiFi_close() function should be called when use of the host driver APIs is complete.
5.14.5 Instrumentation
The WiFi driver provides instrumentation data by both making Log calls and by sending data to the ROV
tool in CCS.
5.14.5.1 Logging
The WiFi driver is instrumented with Log events that can be viewed with UIA and RTOS Analyzer. Diags
masks can be turned on and off to provide granularity to the information that is logged. Use
Diags_USER1 to see general Log events. The WiFi driver logs the following actions using the Log_print()
APIs provided by SYS/BIOS.
•
WiFi device enabled or disabled
•
Interrupts enabled or disabled
•
WiFi_open() success or failure
•
WiFi_close() success
•
Send or receive buffer overrun
•
Reads and writes to WiFi device completed
•
SPI_transfer() failure
5.14.5.2 ROV
In the ROV tool, the following information about the WiFi driver is shown:
•
Function table
•
WiFi handle
•
IRQ interrupt vector ID number
•
SPI handle
•
SPI state machine state
5.14.6 Examples
See the TI-RTOS Getting Started Guide (SPRUHD3) for a list of examples that use the WiFi driver.
SPRUHD4F—April 2014 TI-RTOS Utilities 88
Submit Documentation Feedback
Chapter 6
SPRUHD4F—April 2014
TI-RTOS Utilities
This chapter provides information about utilities provided by TI-RTOS.
6.1 Overview
Utilities for use with TI-RTOS are provided in the
<tirtos_install>\packages\ti\tirtos\utils
directory. This chapter describes such modules.
6.2 SysFlex Module
The SysFlex module (ti.tirtos.utils.SysFlex) has been deprecated. Applications should use the
xdc.runtime.SysCallback module instead.
6.3 UARTMon Module
The UARTMon module (ti.tirtos.utils.UARTMon) enables host communication with a target device using
the target’s UART. The target device can respond to requests to read and write memory at specified
addresses. CCS includes features that allow you to leverage this utility to monitor the target device with
the Debug view or with GUI Composer.
The GPIO example enables the UARTMon module. See the readme file in the example project for
information about the example.
6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.2 SysFlex Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.3 UARTMon Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.4 UART Example Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Topic Page
SPRUHD4F—April 2014 TI-RTOS Utilities 89
Submit Documentation Feedback
www.ti.com UARTMon Module
To use UARTMon in your application, open the project’s *.cfg file with the XGCONF Configuration Editor.
Select the TIRTOS module, and choose the
System Overview
to see the diagram below. Right-click on
the
UART Monitor
module and select
Use UARTMon
from the drop-down to add it to your application.
No extra user code is needed on the target to use this utility.
To configure this module, select
UARTMon
in the Outline pane to view its configuration page.
The UART Index property is the board index of the UART peripheral to be used as a monitor. In the
Board.h file, Board_UART0 has an index of 0 and Board_UART1 has an index of 1. Other options that
can be adjusted are the baud rate for the UART and the priority and stack size for the Task that performs
the monitoring.
90 TI-RTOS Utilities SPRUHD4F—April 2014
Submit Documentation Feedback
UARTMon Module www.ti.com
Once UARTMon is enabled in your configuration, a task called UARTMonTask is automatically created
and can be seen among your task instances in XGCONF Configuration Editor as shown below. This task
will also show up in ROV when you are debugging.
The UARTMon module has no C APIs.
The GPIO Interrupt examples for the MSP-EXP430F5529LP, Tiva EK-TM4C123GXL LaunchPad and
Tiva DK-TM4C123G Evaluation Kit boards have UARTMon enabled.
6.3.1 UARTMon with CCS Tools
CCS supports UART communication alongside a JTAG connection. This section explains how to create
the necessary target configuration and run the debug session.
Follow these steps to create a target configuration file that allows you to use a UART Monitor connection
in addition to your existing JTAG connection:
1. Choose
File > New > Target Configuration File
from the CCS menus.
2. Type a filename for this configuration, and click
Finish
. The target configuration will be stored in a
*.ccxml file.
3. In the Target Configuration window, select the
main connection used to communicate with
the device. For example, for Stellaris and Tiva
boards, you might use the
Stellaris In-Circuit
Debug Interface
.
4. To specify the device, begin typing the name
of your device. The filter field shows only
those devices that match what you type.
5. When you see your device, check the box
next to it.
6. If the device you select has a UART on its
board, you see the Alternate Communication
area to the right of the device selection.
SPRUHD4F—April 2014 TI-RTOS Utilities 91
Submit Documentation Feedback
www.ti.com UARTMon Module
7. Make sure UART Communication is selected in the drop-down list. It is typically the only option.
Note:
When using a driver based on the Tiva In-Circuit Debug Interface (ICDI) or an MSP430
driver, the COM Port must have the same number as one identified in the Windows
Device manager. When using a XDSv2 USB Emulator, there is no such limitation; the
emulator can create a new COM port.
8. Click the
Add
button and select the
ComPort
that is created.
9. Modify the
COM Port
and
Baud Rate
as needed.
10. Click
Save
to save your target configuration file.
92 TI-RTOS Utilities SPRUHD4F—April 2014
Submit Documentation Feedback
UARTMon Module www.ti.com
To run and debug a program that has the UARTMon module enabled, follow these steps:
1. Build your application if you have not already done so.
2. Choose
Run > Debug Configurations
from the CCS menus.
3. Expand the
Code Composer Studio - Device Debugging
category and select the target
configuration you just created. (If your target configuration file is not listed under the Device
Debugging category, close this dialog, launch the target configuration, and then re-open the Debug
Configuration dialog to cause the new target configuration to be listed.)
4. In the right page of the dialog, choose the
Program
tab.
5. Make sure the interface or emulator used for non-UART communication is selected in the
Device
drop-down list. For example, for Tiva and Stellaris boards, you might be using the
Stellaris In-Circuit
Debug Interface
.
6. If your project is not already selected for the non-UART interface or emulator, click
Workspace
in the
Project
row and select the project you want to debug. Click
OK
.
7. Select the
Load program
loading option for this device.
8. Move back up to the
Device
drop-down list. This time, select the
UARTConnection_0/ComPort
option in the
Device
drop-down list.
9. If your project is not already selected for the UART connection, click
Workspace
in the
Project
row
and select the project you want to debug. Click
OK
.
10. Select the
Load symbols only
loading option for this device. If you skip this step, the debugger will
attempt to program the device using the UART connection.
11. Click
Debug
.
SPRUHD4F—April 2014 TI-RTOS Utilities 93
Submit Documentation Feedback
www.ti.com UARTMon Module
12. In the Debug view, the UARTConnection is listed among the available connections and is marked as
Running, meaning that the COM Port specified is now being listened to.
13. If you configured the project to enable UARTMon as described in the previous section, you can select
the UART connection to watch variables and expressions the same way you would with an emulator.
In this example, the count variable in the Expressions window is being watched using the UART
Connection when that item is selected. If the Stellaris In-Circuit Debug Interface is selected, that
connection is used to watch the same variable.
94 TI-RTOS Utilities SPRUHD4F—April 2014
Submit Documentation Feedback
UART Example Implementation www.ti.com
6.3.2 GUI Composer
GUI Composer is a tool in CCS for creating custom graphical user interfaces that interact with your target
application. You can use it to create interface widgets that are bound to variables in the running target
and update themselves accordingly. With UARTMon included in your application, GUI Composer can
use the UART connection to interact with the running target.
For example, the count variable shown in the previous section can be bound to a dial widget in GUI
Composer. When the value of the count variable changes on the target, the UART connection is used to
change the reading on the dial. In addition, you can use the dial to set the value of the count variable on
the target. To learn more about GUI Composer, see the Texas Instruments Wiki.
6.4 UART Example Implementation
The
UARTUtils.c
file provides an example implementation using a UART. Three of the System functions
are initialized (the others default to NULL) in the
uartconsole.cfg
file. The example uses the
SysCallback module provided by XDCtools.
The configuration source is as follows. These statements create the same configuration as the graphical
settings shown in Section 6.2:
var SysCallback = xdc.useModule('xdc.runtime.SysCallback');
SysCallback.abortFxn = "&UARTUtils_systemAbort";
SysCallback.putchFxn = "&UARTUtils_systemPutch";
SysCallback.readyFxn = "&UARTUtils_systemReady";
System.SupportProxy = SysCallback;
In
uartconsole.c
, main() does the following
1. Calls the board-specific setupUART() function to initialize the UART peripheral.
2. Calls UARTUtils_systemInit() as follows to initialize the UART 0 software. After the
UARTUtils_systemInit function is called, any System_printf output will be directed to UART 0.
/* Send System_printf to the UART 0 also */
UARTUtils_systemInit(0);
SPRUHD4F—April 2014 Using the FatFs File System Drivers 95
Submit Documentation Feedback
Chapter 7
SPRUHD4F—April 2014
Using the FatFs File System Drivers
This chapter provides an overview of FatFs and discusses how FatFs is interconnected and used with
TI-RTOS and SYS/BIOS.
7.1 Overview
FatFs is a free, 3rd party, generic File Allocation Table (FAT) file system module designed for embedded
systems. The module is available for download at http://elm-chan.org/fsw/ff/00index_e.html along with
API documentation explaining how to use the module. Details about the FatFs API are not discussed
here. Instead, this section gives a high-level explanation about how it is integrated with TI-RTOS and
SYS/BIOS.
The FatFs drivers provided by TI-RTOS enable you to store data on removable storage media such as
Secure Digital (SD) cards and USB flash drives (Mass Storage Class). Such storage may be a convenient
way to transfer data between embedded devices and conventional PC workstations.
7.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
7.2 FatFs, SYS/BIOS, and TI-RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
7.3 Using FatFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
7.4 Cautionary Notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Topic Page
96 Using the FatFs File System Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
FatFs, SYS/BIOS, and TI-RTOS www.ti.com
7.2 FatFs, SYS/BIOS, and TI-RTOS
SYS/BIOS provides a FatFS module. TI-RTOS extends this feature by supplying "FatFs" drivers that link
into the SYS/BIOS FatFs implementation. The FatFS module in SYS/BIOS is aware of the multi-threaded
environment and protects itself with OS primitives supplied by SYS/BIOS.
Figure 7-1 FatFs data flow
From the start of this data flow to the end, the components involved behave as follows:
•
Application.
The top application layer calls the basic open, close, read, and write functions. Users
who are familiar with FatFs can easily use the FatFs API, which is documented at the module’s
download site. Alternatively, SYS/BIOS also connects the C input/output (C I/O) runtime support
library in TI’s Code Generation Tools to FatFs. You can call familiar functions such as fopen(),
fclose(), fread(), and fwrite(). Functionally, the C I/O interface and the FatFs APIs perform the same
operations (with a few exceptions described in Section 7.3).
•
FatFS module.
The next layer, the ti.sysbios.fatfs.FatFS module, is provided as part of SYS/BIOS.
This module handles the details needed to manage and use the FAT file system, including the
media’s boot sector, FAT tables, root directories, and data regions. It also protects its functions in a
multi-threaded environment. Internally, the FatFS module makes low-level data transfer requests to
the Disk IO functions described on the FatFs product web page. Implementations of this set of
functions are called "FatFs drivers" in this document.
•
diskIO Function table.
To allow products to provide multiple FatFs drivers, the SYS/BIOS FatFS
module contains a simple driver table. You can use this to register multiple FatFs drivers at runtime.
Based on the drive number passed through FatFs, the driver table routes FatFs calls to a particular
FatFs driver.
SPRUHD4F—April 2014 Using the FatFs File System Drivers 97
Submit Documentation Feedback
www.ti.com Using FatFs
•
FatFs drivers.
The last layer in Figure 7-1 is the FatFs drivers. TI-RTOS comes with pre-built FatFs
drivers that plug into the FatFS module provided by SYS/BIOS. A FatFs driver has no knowledge of
the internal workings of FatFs. Its only task is to perform disk-specific operations such as
initialization, reading, and writing. The FatFs driver performs read and write operations in data block
units called sectors (commonly 512 bytes). Details about writing data to the device are left to the
particular FatFs driver, which typically accesses a peripheral’s hardware registers or uses a driver
library.
7.3 Using FatFs
The subsections that follow show how to configure FatFs statically, how to prepare the FatFs drivers for
use in your application, and how to open files. For details about performing other file-based actions once
you have opened a file, see the FatFs APIs described on http://elm-chan.org/fsw/ff/00index_e.html in the
"Application Interface" section or the standard C I/O functions.
The TI-RTOS F28M3x Demo example and all 3 FatFs File Copy examples use FatFs with the SDSPI
driver. The FatSD USB Copy example uses the USBMSCHFatFs driver.
7.3.1 Static FatFS Module Configuration
To incorporate the SYS/BIOS FatFS module into an application, simply "use" this module in a
configuration (.cfg) file. You can do this by searching the
Available Products
list in the XGCONF
Configuration Editor for FatFS, selecting the SYS/BIOS FatFS module, and checking the
Enable FAT
File System in My Application
box. Or, you can add the following statement to the .cfg file.
var FatFS = xdc.useModule('ti.sysbios.fatfs.FatFS');
Note:
The name of the product and the drivers is "FatFs" with a lowercase "s". The name of
the SYS/BIOS module is "FatFS" with an uppercase "S". If you are using a text editor
to write configuration statements, be sure to use the uppercase "S". If you are using the
XGCONF Configuration Editor to edit your configuration graphically, the correct
capitalization is used automatically.
By default, the prefix string used in C I/O fopen() calls that uses this module is "fat" and no RAM disk is
created. You can these defaults by modifying the FatFS module properties.
For example, you can change the C I/O prefix string used in fopen() calls by adding this line to the .cfg file:
FatFS.fatfsPrefix = “newPrefix”;
The application would then need to use the prefix in C I/O fopen() calls as follows:
src = fopen(“newPrefix:0:signal.dat”, "w");
See the online help for the module for more details about FatFS configuration.
You will also need to configure the FatFs driver or drivers you want to use. See Section 5.9, SDSPI Driver
and Section 5.10, USBMSCHFatFs Driver for details.
98 Using the FatFs File System Drivers SPRUHD4F—April 2014
Submit Documentation Feedback
Using FatFs www.ti.com
7.3.2 Defining Drive Numbers
Calls to the open() functions of individual FatFs drivers—for example, SDSPI_open()—require a drive
number argument. Calls to the C I/O fopen() function and the FatFs APIs also use the drive number in
the string that specifies the file path. The following C code defines driver numbers to be used in such
functions:
/* Drive number used for FatFs */
#define SD_DRIVE_NUM 0
#define USB_DRIVE_NUM 1
Here are some statements from the FatSD USB Copy example that use these drive number definitions.
Note that STR(SD_DRIVE_NUM) uses a MACRO that expands SD_DRIVE_NUM to 0.
SDSPI_Handle sdspiHandle;
SDSPI_Params sdspiParams;
FILE *src;
const Char inputfilesd[] = "fat:"STR(SD_DRIVE_NUM)":input.txt";
/* Mount and register the SD Card */
SDSPI_Params_init(&sdspiParams);
sdspiHandle = SDSPI_open(Board_SDSPI0, SD_DRIVE_NUM, &sdspiParams);
/* Open the source file */
src = fopen(inputfilesd, "r");
7.3.3 Preparing FatFs Drivers
In order to use a FatFs driver in an application, you must do the following:
•
Include the header file for the driver.
For example:
#include <ti/drivers/SDSPI.h>
•
Run the initialization function for the driver.
All drivers have init() functions—for example,
SDSPI_init()—that need to be run in order to set up the hardware used by the driver. Typically, these
functions are run from main(). In the TI-RTOS examples, a board-specific initialization function for the
driver is run instead of running the driver’s initialization function directly. For example:
Board_initSDSPI();
•
Open the driver.
The application must open the driver before the FatFs can access the drive and its
FAT file system. Similarly, once the drive has been closed, no other FatFs calls shall be made. All
drivers have open() functions—for example, SDSPI_open()—that require a drive number to be
passed in as an argument. For example:
sdspiHandle = SDSPI_open(Board_SDSPI0, SD_DRIVE_NUM, NULL);
See Section 5.9, SDSPI Driver and Section 5.10, USBMSCHFatFs Driver for details about the FatFs
driver APIs.
SPRUHD4F—April 2014 Using the FatFs File System Drivers 99
Submit Documentation Feedback
www.ti.com Cautionary Notes
7.3.4 Opening Files Using FatFs APIs
Details on the FatFs APIs can be found at http://elm-chan.org/fsw/ff/00index_e.html in the "Application
Interface" section.
The drive number needs to be included as a prefix in the filename string when you call f_open() to open
a file. The drive number used in this string needs to match the drive number used to open the FatFs
driver. For example:
res = f_open(&fsrc, “SD_DRIVE_NUM:source.dat”, FA_OPEN_EXISTING | FA_READ);
res = f_open(&fdst, “USB_DRIVE_NUM:destination.dat”, FA_CREATE_ALWAYS | FA_WRITE);
A number of other FatFs APIs require a path string that should include the drive number. For example,
f_opendir(), f_mkdir(), f_unlink(), and f_chmod().
Although FatFs supports up to 10 (0-9) drive numbers, the SYS/BIOS diskIO function table supports only
up to 4 (0-3) drives. You can modify this default by changing the definition of _VOLUMES in the ffconf.h
file in the SYS/BIOS FatFS module. You will then need to rebuild SYS/BIOS as described in the
SYS/BIOS User’s Guide (SPRUEX3).
It is important to use either the FatFs APIs or the C I/O APIs for file operations. Mixing the APIs in the
same application can have unforeseen consequences.
7.3.5 Opening Files Using C I/O APIs
The C input/output runtime implementation for FatFs works similarly to the FatFs API. However, you must
add the file name prefix configured for the FatFS module ("fat" by default) and the logical drive number
as prefixes to the filename. The file name prefix is extracted from the filename before it gets passed to
the FatFs API.
In this example, the default file name prefix is used and the drive number is 0:
fopen(“fat:0:input.txt”, "r");
It is important to use either the FatFs APIs or the C I/O APIs for file operations. Mixing the APIs in the
same application can have unforeseen consequences.
7.4 Cautionary Notes
FatFs drivers perform data block transfers to and from physical media. Depending on the FatFs driver,
writing to and reading from the disk could prevent lower-priority tasks from running during that time. If the
FatFs driver blocks for the entire transfer time, only higher-priority SYS/BIOS Tasks, Swis or Hwis can
interrupt the Task making FatFs calls. In such cases, the application developer should consider how often
and how much data needs to be read from or written to the media.
By default the SYS/BIOS FatFS module keeps a complete sector buffered for each opened file. While
this requires additional RAM, it helps mitigate frequent disk operations when operating on more than one
file simultaneously.
The SYS/BIOS FatFS implementation allows up to four unique volumes (or drives) to be registered and
mounted.
SPRUHD4F—April 2014 Rebuilding TI-RTOS 100
Submit Documentation Feedback
Chapter 8
SPRUHD4F—April 2014
Rebuilding TI-RTOS
This chapter describes how and when to rebuild TI-RTOS and components of TI-RTOS.
8.1 Rebuilding TI-RTOS
In most cases, you will not need to rebuild the TI-RTOS libraries. Pre-built libraries for CCS, IAR, and
GCC are provided when you install TI-RTOS. However, if you want to change the compiler or linker
options, you may need to rebuild the libraries.
8.1 Rebuilding TI-RTOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8.2 Rebuilding MSP430Ware's driverlib for TI-RTOS and Its Drivers. . 103
8.3 Rebuilding Individual Components. . . . . . . . . . . . . . . . . . . . . . . . . . 103
Topic Page
SPRUHD4F—April 2014 Rebuilding TI-RTOS 101
Submit Documentation Feedback
www.ti.com Rebuilding TI-RTOS
8.1.1 Building TI-RTOS for CCS
By default, TI-RTOS is ready to be rebuilt for use with CCS from a top-level make file called
tirtos.mak
.
If TI-RTOS is installed in
c:\ti
, you can print a list of available make rules by running the following
command from a command shell window:
To rebuild the TI-RTOS drivers and several of its included components (SYS/BIOS, IPC, NDK, and UIA),
for example, you can run the following:
If you installed CCS and TI-RTOS in a location other than
c:\ti
, you can edit the definition of
DEFAULT_INSTALLATION_DIR in
tirtos.mak
to point to this location. Note that all other product
installation locations are defined relative to the DEFAULT_INSTALLATION_DIR, but you can adjust them
as necessary. You can also pass in installation locations as necessary. For example to use a different
location for XDCtools, do the following:
The following list (from TI-RTOS for MSP430 for example) shows items you can change and sample
values. The
tirtos.mak
file differs for each device family. The version numbers in your copy of the
tirtos.mak
file will match the versions of the components installed with TI-RTOS.
If you are rebuilding on Linux, change all of the Windows paths in the
tirtos.mak
file to Linux paths.
The
CCS_BUILD?=true
flag in the
tirtos.mak
file causes TI-RTOS to be rebuilt for CCS by default.
Other supported tool-chains (such as IAR) also have flags that can be turned on to build for them as well.
If these are not needed, keep them turned off for a faster build.
% cd <tirtos_install>
% ../<xdctools>/gmake –f tirtos.mak
% ../<xdctools>/gmake -f tirtos.mak all
% ../<xdctools>/gmake –f tirtos.mak XDCTOOLS_INSTALLATION_DIR=c:/ti/xdctools_version
CCS_BUILD ?= true
DEFAULT_INSTALLATION_DIR := c:/ti
ti.targets.msp430.elf.MSP430X ?=$(DEFAULT_INSTALLATION_DIR)/ccsv6/tools/compiler/msp430_4.3.1
XDCTOOLS_INSTALLATION_DIR ?= $(DEFAULT_INSTALLATION_DIR)/xdctools_3_30_01_23_core
export XDCTOOLS_JAVA_HOME ?= $(DEFAULT_INSTALLATION_DIR)/ccsv6/eclipse/jre
TIRTOS_INSTALLATION_DIR := $(DEFAULT_INSTALLATION_DIR)/tirtos_msp430_2_00_00_21
BIOS_INSTALLATION_DIR ?= $(TIRTOS_INSTALLATION_DIR)/products/bios_6_40_00_13
UIA_INSTALLATION_DIR ?= $(TIRTOS_INSTALLATION_DIR)/products/uia_2_00_00_27
MSP430WARE_INSTALLATION_DIR ?=$(TIRTOS_INSTALLATION_DIR)/products/MSP430Ware_1_80_01_03a
MSP430HEADERS ?= $(DEFAULT_INSTALLATION_DIR)/ccsv6/ccs_base/msp430/include
102 Rebuilding TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Rebuilding TI-RTOS www.ti.com
8.1.2 Building TI-RTOS for IAR
By default, TI-RTOS is not rebuilt for use with IAR when you run the top-level
tirtos.mak
make file. To
rebuild TI-RTOS for IAR Embedded Workbench, follow these steps:
1. Edit the
tirtos.mak
file and find the following lines:
2. Set the IAR_BUILD flag to true in
tirtos.mak
. Alternately, you can pass a different value on the
make command line as follows:
3. Change the IAR compiler installation directory to match the location where you installed IAR.
Alternately, you can pass a different value on the make command line as follows:
4. Modify the installation locations as needed for the components of TI-RTOS (SYS/BIOS, IPC, NDK
and UIA) that you want to rebuild for IAR.
For a faster build, you can turn off TI-RTOS building for CCS by setting the CCS_BUILD flag to false.
8.1.3 Building TI-RTOS for GCC
By default, TI-RTOS is not rebuilt for GCC when you run the top-level
tirtos.mak
make file. The GCC
code generator used is the Linaro distribution gcc-arm-none-eabi-4_7-2012q4 version that ships with
CCS. To rebuild TI-RTOS with GCC, follow these steps:
1. Edit the
tirtos.mak
file and find the following lines:
2. Set the above GCC_BUILD flag to true in
tirtos.mak
. Alternately, you can pass a value on the make
command line as follows:
3. If you installed CCS in a location other than c:\ti, change the path for GCC_INSTALLATION_DIR to
specify the correct location. Alternately, you can pass a different value on the make command line as
follows:
4. Modify the installation locations as needed for the components of TI-RTOS (SYS/BIOS, IPC, NDK
and UIA) that you want to rebuild for GCC.
For a faster build, you can turn off TI-RTOS building for CCS and IAR by setting the CCS_BUILD and
IAR_BUILD flags to false.
IAR_BUILD ?= false
IAR_COMPILER_INSTALLATION_DIR ?= C:/Program Files (x86)/IAR Systems/Embedded Workbench 6.5
% ../<xdctools>/gmake -f tirtos.mak all IAR_BUILD=true
% ../<xdctools>/gmake -f tirtos.mak all IAR_COMPILER_INSTALLATION_DIR=YOUR_PATH
GCC_BUILD ?= false
GCC_INSTALLATION_DIR := $(DEFAULT_INSTALLATION_DIR)/ccsv6/tools/compiler/gcc-
arm-none-eabi-4_7-2013q3
% ../<xdctools>/gmake -f tirtos.mak all GCC_BUILD=true
% ../<xdctools>/gmake -f tirtos.mak all GCC_INSTALLATION_DIR=YOUR_PATH
SPRUHD4F—April 2014 Rebuilding TI-RTOS 103
Submit Documentation Feedback
www.ti.com Rebuilding MSP430Ware's driverlib for TI-RTOS and Its Drivers
8.2 Rebuilding MSP430Ware's driverlib for TI-RTOS and Its Drivers
The TI-RTOS drivers for MSP430 depend on MSP430Ware's driverlib as an abstraction layer to access
peripheral registers. This level of abstraction promotes code reusability and scales well for TI-RTOS
drivers, because device specifics are stored in driverlib.
To reduce the build time of CCS projects and to be consistent with other TI driverlib components,
MSP430Ware's driverlib source files have been compiled into a library in the TI-RTOS installation.
TI-RTOS provides prebuilt TI-RTOS drivers and prebuilt MSP430Ware driverlib libraries only for the
MSP430F5529. Libraries for other MSP430F5xx and MSP430F6xx devices can be added by editing the
tirtos.mak
file. To build TI-RTOS drivers for other MSP430F5xx or MSP430F6xx devices, add devices
to the MSP430DEVLIST variable (with spaces between the devices in the list). For example, the following
modification to the
tirtos.mak
file causes MSP430Ware's driverlib and TI-RTOS drivers to be built for
both MSP430F5529 and MSP430F6779.
After updating the MSP430DEVLIST variable, rebuild the TI-RTOS drivers as follows:
8.3 Rebuilding Individual Components
The MWare and TivaWare rebuilding mechanism is substantially different from the TI-RTOS rebuilding
mechanism. See the documentation for these products for details.
Driver libraries in the versions of MWare and TivaWare distributed with TI-RTOS have been rebuilt. For
details, see the TI-RTOS.README file in the top-level folder of the MWare and TivaWare components
within the TI-RTOS installation.
# To build TI-RTOS driver libraries for other MSP430 devices; simply append the
# device names to MSP430DEVLIST (separated by whitepsaces)
# MSP430DEVLIST := \
# MSP430F5529 \
# MSP430F5527 \
# MSP430F6459 \
# etc...
#
MSP430DEVLIST := MSP430F5529 MSP430F6779
% cd <tirtos_install>
% ../<xdctools>/gmake -f tirtos.mak drivers
SPRUHD4F—April 2014 Memory Usage with TI-RTOS 104
Submit Documentation Feedback
Chapter 9
SPRUHD4F—April 2014
Memory Usage with TI-RTOS
This chapter provides links to information about memory usage.
9.1 Memory Footprint Reduction
Many configuration parameters impact the size (both code and data) of a TI-RTOS application. This
section discusses the approaches TI-RTOS takes to minimize the size of its examples. For a more
detailed discussion on how to reduce the size of the kernel, please refer to the SYS/BIOS User’s Guide
(SPRUEX3) appendix on "Minimizing the Application Footprint."
The TI-RTOS examples are divided into the following types of examples:
•
Peripheral Examples.
These examples are designed to demonstrate the usage of a peripheral or
feature. These examples are designed to have a small footprint and make use of many of the
strategies described in this section.
•
Demo Examples.
The demo examples are "kitchen-sink" examples; that is, they use a wide variety
of features. There is no overall design of the memory use strategy for these demos. Decisions were
made to allow the program to fit into the available memory of the target device, while still showcasing
multiple peripherals and features.
•
Empty Examples.
Two different "Empty" examples can be created with the New Project Wizard if
you are using CCS. These examples are intended as a starting point for new development. The two
different types of “Empty” projects are:
— Empty (Minimal) Project:
Disables kernel features and debug capabilities to minimize the
footprint.
— Empty Project:
Enables more kernel features and debug capabilities at the cost of a larger
footprint.
9.1 Memory Footprint Reduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
9.2 Networking Stack Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Topic Page
SPRUHD4F—April 2014 Memory Usage with TI-RTOS 105
Submit Documentation Feedback
www.ti.com Memory Footprint Reduction
The footprint reduction approaches described in this section are generally not used in the "Empty"
examples, but are used in the "Empty (Minimal)" examples. The exceptions are that the SysMin module
and the custom BIOS library (with asserts and logging enabled) are used in the Empty examples. Any
other configuration changes described here can be made to the Empty examples if needed.
The peripheral examples (available in TI Resource Explorer in CCS) are designed to have a small
footprint. The UART examples are exceptions to this rule, because along with UART functionality they
are intended to show various approaches for debugging an application.
The following configuration changes help reduce both the data and code footprint in the TI-RTOS
peripheral examples. You may want to use these strategies in your own applications.
For most configuration changes, both the graphical (XGCONF) and script-based methods of modifying
the configuration are shown. Use whichever method you prefer.
Non-Instrumented TI-RTOS drivers:
The TI-RTOS drivers come with both instrumented and non-
instrumented libraries. The instrumented libraries contain trace statements (Log_printN() calls) and
assert checking (Assert_isTrue() calls). The non-instrumented libraries do not contain these statements.
All the peripheral examples use the non-instrumented TI-RTOS driver libraries.
An example’s *.cfg file contains statements like the following for drivers used by the example:
var I2C = xdc.useModule('ti.drivers.I2C');
I2C.libType = I2C.LibType_NonInstrumented;
106 Memory Usage with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Memory Footprint Reduction www.ti.com
BIOS Custom Library:
The kernel comes with both instrumented and non-instrumented libraries. In
addition, it can perform a custom build to include only functionality required by the application. The TI-
RTOS peripheral examples use the custom build. They also disable the kernel’s logging and assert
checking. See the "Compiler and Linker Optimization" section of the SYS/BIOS User’s Guide for details.
If you edit configuration scripts directly, these statements have the same effect as the XGCONF settings
above:
var BIOS = xdc.useModule('ti.sysbios.BIOS');
BIOS.libType = BIOS.LibType_Custom;
BIOS.logsEnabled = false;
BIOS.assertsEnabled = false;
SPRUHD4F—April 2014 Memory Usage with TI-RTOS 107
Submit Documentation Feedback
www.ti.com Memory Footprint Reduction
Minimal System Provider:
The System module allows users to plug in different System Support
Proxies. Each proxy has pros and cons See Section 3.2.1, Output with printf(), page 3-27 for details about
the available System module proxies. Most TI-RTOS peripheral examples use the smaller SysMin proxy,
which uses an internal buffer to store System output. The size of the buffer is also reduced.
If you edit configuration scripts directly, these statements have the same effect as the XGCONF settings
above:
Note:
The System output can be viewed in the RTOS Object Viewer (ROV) in CCS.
System Stack Size:
The Hwi and Swi threads share a single System stack. Each device has a default
System stack size, which is set by the Program.stack property. Several TI-RTOS examples (especially
the MSP430 examples) do not use the default value. Instead, the Program.stack property is set in the
example’s .cfg file.
Note:
The non-MSP430 examples do not reduce stack size as aggressively as the MSP430 examples.
This is because the non-MSP430 example’s source code (*.c and *.cfg) are generic and must run on
several different devices.
var System = xdc.useModule('xdc.runtime.System');
var SysMin = xdc.useModule('xdc.runtime.SysMin');
System.SupportProxy = SysMin;
SysMin.bufSize = 128;
108 Memory Usage with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Memory Footprint Reduction www.ti.com
To determine the best value for this property, each example was run with the default Program.stack
setting. After an example ran under all conditions, the ROV in CCS was used to examine Hwi usage. The
"Module" tab for Hwi objects shows the stack’s peak usage. The example’s Program.stack was set to a
size higher than the peak but lower than the default. For example:
If you edit configuration scripts directly, this statement has the same effect as the XGCONF setting above:
Program.stack = 0x200;
SPRUHD4F—April 2014 Memory Usage with TI-RTOS 109
Submit Documentation Feedback
www.ti.com Memory Footprint Reduction
Static Tasks:
The majority of the examples statically create their Tasks in their *.cfg files. This reduces
the code footprint because code is not needed for functions such Task_create().
To statically create a task, go to the
Instance
panel for configuring the Task module and click
Add
.
An example’s *.cfg file contains statements like the following to statically create an object used by the
example:
var taskParams = new Task.Params();
taskParams.instance.name = "taskFxn";
taskParams.stackSize = 0x300;
Program.global.task = Task.create("&taskFxn", task0Params);
110 Memory Usage with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Memory Footprint Reduction www.ti.com
Task Stack Size:
Each Task thread in the application has its own stack. Each device has a default Task
stack size. Many examples (especially the MSP430 examples) do not use the default value. Instead, the
Task.stackSize property is set in the example’s *.cfg file.
Note:
The non-MSP430 examples do not reduce stack size as aggressively as the MSP430 examples.
This is because the non-MSP430 example’s source code (*.c and *.cfg) are generic and must run on
several different devices.
To determine the best value for this property, each example was run with the default stackSize. After
letting a example run under all conditions, the ROV in CCS was used to examine Task usage. The
"Detailed" tab for Task objects shows the stack peak usage. The stackSize for each Task was set to a
size higher than the peak but lower than the default. For example:
If you edit configuration scripts directly, this statement has the same effect as the XGCONF setting above:
taskParams.stackSize = 0x300;
SPRUHD4F—April 2014 Memory Usage with TI-RTOS 111
Submit Documentation Feedback
www.ti.com Memory Footprint Reduction
Memory allocation:
None of the TI-RTOS drivers allocate memory, except for the EMAC and
USBMSCHFatFs drivers. The examples do not allocate memory either, except for the networking (wired
and wireless) and USB examples. The examples statically create all kernel objects (such as Tasks and
Semaphores) in the *.cfg file. This is done because run-time creation of kernel object allocates memory
dynamically. Of course, for real applications, run-time object creation might be required.
Note that the networking stack allocates memory from a heap, so this approach cannot be used if the
networking stack is used.
If you edit configuration scripts directly, disable dynamic memory allocation by removing the following
statement from an example’s *.cfg file:
In addition, add the following statement to the example’s *.cfg file:
var HeapMem = xdc.useModule('ti.sysbios.heaps.HeapMem');
BIOS.heapSize = 0;
112 Memory Usage with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Memory Footprint Reduction www.ti.com
No Idle Task:
The kernel, by default, has an Idle task that runs if no other thread is running. The Idle task
runs low-priority functions (for example, to check for stack overflows). For the MSP430 examples, the Idle
task is not enabled. This allows the MSP430 to be placed in a power-saving mode.
If you edit configuration scripts directly, this statement has the same effect as the XGCONF setting above:
Task.enableIdleTask = false;
SPRUHD4F—April 2014 Memory Usage with TI-RTOS 113
Submit Documentation Feedback
www.ti.com Memory Footprint Reduction
Stack Checking:
The kernel, by default, verifies that the System stack and Tasks stacks have not
overflowed. The System stack checks are performed in the Idle Task. The Task stack checks are
performed at every context switch. The top of the stack is examined to make sure it has the correct
"magic" value. Since a overflowed Task or System stack is show in ROV, the Task stack check was
removed from the MSP430 examples to reduce the code footprint. See the SYS/BIOS User’s Guide for
details about these properties.
If you edit configuration scripts directly, these statements have the same effect as the XGCONF settings
above:
Task.checkStackFlag = false;
Hwi.checkStackFlag = false;
114 Memory Usage with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Memory Footprint Reduction www.ti.com
Software interrupts (Swis) disabled:
The kernel, by default, enables software interrupts. For examples
that do not use Swis, this type of thread is disabled. See the SYS/BIOS User’s Guide for details about
Swis. Note the EMAC driver uses a Swi, so networking examples cannot use this trick.
If you edit configuration scripts directly, this statement has the same effect as the XGCONF setting above:
Number of Task Priorities:
The kernel allows Tasks to have different priorities. See the SYS/BIOS
User’s Guide for details about Task priorities. The TI-RTOS examples lower the maximum number of
Task priorities to 4.
If you edit configuration scripts directly, this statement has the same effect as the XGCONF setting above:
BIOS.swiEnabled = false;
Task.numPriorities = 4;
SPRUHD4F—April 2014 Memory Usage with TI-RTOS 115
Submit Documentation Feedback
www.ti.com Memory Footprint Reduction
Number of atexit functions:
The kernel allows System atexit() functions to be registered. See the
XDCtools API reference online help (CDOC) for more about the xdc.runtime.System module’s atexit()
functions. The TI-RTOS examples lower the maximum number of System atexit functions to 2.
If you edit configuration scripts directly, this statement has the same effect as the XGCONF setting above:
Kernel exception handling (for ARM):
By default the kernel plugs in an exception handler to make
debugging an exception easier. The exception handler can be removed to reduce code footprint. It is
recommended that you leave the exception handler in place during development.
If you edit configuration scripts directly, these statements have the same effect as the XGCONF setting:
System.maxAtexitHandlers = 2;
var m3Hwi = xdc.useModule('ti.sysbios.family.arm.m3.Hwi');
m3Hwi.excHandlerFunc = null;
116 Memory Usage with TI-RTOS SPRUHD4F—April 2014
Submit Documentation Feedback
Networking Stack Memory Usage www.ti.com
Strings:
Since no logging or asserts are enabled for the TI-RTOS examples, the strings associated with
those facilities can be omitted. However, removing the strings for logging and asserts also removes
additional strings. See the XDCtools API reference online help (CDOC) for more about the
xdc.runtime.Text module’s isLoaded property.
If you edit configuration scripts directly, this statement has the same effect as the XGCONF setting above:
9.2 Networking Stack Memory Usage
See TI-RTOS Networking Stack Memory Usage on the Texas Instruments Wiki for details about to
adjusting memory usage of the networking stack (NDK).
Text.isLoaded = false;
SPRUHD4F—April 2014 Revision History 117
Submit Documentation Feedback
Appendix A
SPRUHD4F—April 2014
Revision History
Table A–1 lists the significant changes made in recent versions of this document.
Table A–1. Revision History
Revision Chapter Location Additions/Modifications/Deletions
SPRUHD4F Preface Current software version number is v2.00.
About Section 1.1 TI-RTOS now has separate installers for various device
families. There is a separate TI-RTOS Getting Started
Guide for each installer.
Section 1.2 TI-RTOS has several components with TI-RTOS
component names. For example, SYS/BIOS is also called
the TI-RTOS Kernel.
Instrumentation Section 2.1 System Analyzer also includes the views available from the
Tools > RTOS Analyzer menu.
Section 2.2 and
Section 2.3.3
The configuration properties for LoggingSetup have
changed.
Section 2.5 The menu commands and dialogs used to open System
Analyzer views have changed.
Board-Specific Section 4.1 TI-RTOS examples have been added for the MSP-
EXP430FR5969LP LaunchPad and EK_TM4C1294XL
Evaluation Kit.
Drivers Section 5.2.6 EUSCI versions of the MSP430 driver have been added.
Memory Section 9.1 Pictures of configuration settings made in XGCONF are
included to supplement the script-based statements. Also,
instructions for removing the kernel exception handler have
been added.
SPRUHD4E Preface Current software version number is v1.21.
About Section 1.1 and
Section 4.1
Added MSP-EXP430F5529 Experimenter Board.
Debugging Section 3.1 ROV also available in IAR Embedded Workbench.
Rebuilding Section 8.1.3 Added section on building TI-RTOS for the GCC code
generator.
Memory Usage Section 9.1 Two versions of the Empty example are now provided. The
new one uses minimal memory. Also added removal of
HeapMem enabling statement to description of how to
disable dynamic memory allocation.
118 Revision History SPRUHD4F—April 2014
Submit Documentation Feedback
www.ti.com
SPRUHD4D Preface Current software version number is v1.20.
About Section 1.1 Several new boards added to the table.
Section 1.8.3 New section added for MSP430Ware.
Section 1.11 Links added for MSP430Ware, MSP430 boards, and
BoosterPacks.
Examples Chapter 2 Details about individual examples moved to the readme
files within the example projects. Other information previ-
ously in Chapter 2 moved to the TI-RTOS Getting Started
Guide.
Instrumentation Section 2.3 to
Section 2.3.3 New section added on converting an example to perform
run-time uploading of instrumentation data.
Boards Section 4.1 Several new boards added to the table.
Drivers Section 5.2.6 New section added on Hwi objects and ISRs for MSP430
devices.
Section 5.11.1.3 New section added on USB reference modules for
MSP430.
Section 5.14 to
Section 5.14.1
WiFi driver can now be configured to support calling it from
multiple threads.
Utilities Section 6.2 The SysFlex module has been deprecated.
Section 6.3 to
Section 6.3.2
The UARTMon module has been added.
Rebuilding Section 8.1.1 The contents of tirtos.mak have changed.
Section 8.1.2 New section added for building TI-RTOS for IAR.
Section 8.2 New section added for rebuilding MSP430Ware libraries.
Memory Section 9.1 New section added to discuss ways to reduce the memory
footprint.
Table A–1. Revision History
Revision Chapter Location Additions/Modifications/Deletions
SPRUHD4F—April 2014 Index 119
Submit Documentation Feedback
Index
SPRUHD4F—April 2014
Index
A
APIs
common 41
EMAC driver 47
GPIO driver 61
I2C driver 53
SDSPI driver 72
UART driver 49
USB device and host modules 80
USBMSCHFatFs driver 75
Watchdog driver 82
assert handling 26
Available Products list 15
B
board.c files 33
build flow 31
C
C28x
support 32
ccxml file 34
CDC device 36
COM Port 91
components 8
Concerto 32
configuration
build flow 31
configuro tool 31
controlSUITE 11
other documentation 12
D
debugging 25
Demo examples 104
DK-TM4C123G 32
DK-TM4C129X 32
drivers 11, 35
E
EK_TM4C1294XL 32
EK-LM4F120XL 32
EKS-LM4F232 32
EK-TM4C123GXL 32
EMAC driver 35, 46
Empty example 104
Ethernet driver 35, 46
exception handling 26
F
F28M35H52C1 32
F28M36P63C2 32
FatFs driver 71, 74
flash drives 36, 74
G
GPIO driver 35, 60
GPIO pin
configuration 33
GUI Composer 94
H
HID device 36
I
I2C driver 35, 52
instrumentation 14
instrumented libraries 22
IPC 8, 10
other documentation 10
SPI driver for multicore applications 36
K
keyboard
device 80
host 80
L
LEDs
configuration 33
120 Index SPRUHD4F—April 2014
Submit Documentation Feedback
www.ti.com
linker command file 33
LM4F120H5QR 32
LM4F232H5QD 32
Load logging 16
Log module 22
EMAC driver 47
GPIO driver 62
I2C driver 59
UART driver 51
USBMSCHFatFs driver 76
viewing messages 23
Watchdog driver 84, 87
logging 16
LoggingSetup module 15
M
M3 microcontroller 32
memory reduction 104
MessageQ 36
mouse
device 80, 81
host 80
MSC device 36
MSC host 74
MSP430F5529 32
MSP430FR5969 32
MSP430Ware 8, 12
MSP-EXP430F5529LP 32
MSP-EXP430FR5969LP 32
multicore applications 36
MWare 8, 9, 11
other documentation 12
N
NDK 8, 10, 46
other documentation 10
non-instrumented libraries 22
P
Peripheral examples 104
printf() function 27
Printf-style output 26, 27
products directory 8
R
rebuilding
TI-RTOS 100
ROV tool 24, 25, 27
EMAC 47
GPIO 62
I2C 59
SDSPI 73
UART 51
Watchdog driver 84
WiFi driver 87
RTOS Analyzer
debugging with 23
RTOS Object View (ROV) 25
S
SD cards 71
SDSPI driver 35, 71
serial devices 81
simulator, debugging with 34
SPI (SSI) bus 71
SPI driver 36
SPIMessageQTransport transport 36, 69
static configuration 31
StellarisWare 8
SYS/BIOS 8, 9
logging 16
other documentation 9
SysCallback module 27
SysFlex module 27, 88
SysMin module 27
configuration 28
SysStd module 27
System Analyzer 9, 14, 26
System module 27
configuration 28
System_printf() function 27
T
Target Configuration File 34
TI-RTOS 7
TivaWare 12
TM4C123GH6PGE 32
TM4C123GH6PM 32
TM4C1294NCPDT 32
TM4C129XNCZAD 32
TMDXDOCK28M36 32
TMDXDOCKH52C1 32
TMDXDOCKH52C1.c file 33
U
UART driver 36, 48
UARTMon module 88
UIA 8, 9, 14
other documentation 9
USB controller 74
USB Descriptor Tool 78, 79
USB driver 80
USBMSCHFatFs driver 36, 74
W
Watchdog driver 36, 81
APIs 82
configuration 81
SPRUHD4F—April 2014 Index 121
Submit Documentation Feedback
www.ti.com
WiFi driver 36
X
XDCtools 8, 13
build settings 31
other documentation 13
IMPORTANT NOTICE
Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, enhancements, improvements
and other changes to its semiconductor products and services per JESD46, latest issue, and to discontinue any product or service
per JESD48, latest issue. Buyers should obtain the latest relevant information before placing orders and should verify that such
information is current and complete. All semiconductor products (also referred to herein as “components”) are sold subject to TI’s
terms and conditions of sale supplied at the time of order acknowledgment.
TI warrants performance of its components to the specifications applicable at the time of sale, in accordance with the warranty
in TI’s terms and conditions of sale of semiconductor products. Testing and other quality control techniques are used to the extent
TI deems necessary to support this warranty. Except where mandated by applicable law, testing of all parameters of each
component is not necessarily performed.
TI assumes no liability for applications assistance or the design of Buyers’ products. Buyers are responsible for their products
and applications using TI components. To minimize the risks associated with Buyers’ products and applications, Buyers should
provide adequate design and operating safeguards.
TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask
work right, or other intellectual property right relating to any combination, machine, or process in which TI components or services
are used. Information published by TI regarding third-party products or services does not constitute a license to use such products
or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the
patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI.
Reproduction of significant portions of TI information in TI data books or data sheets is permissible only if reproduction is without
alteration and is accompanied by all associated warranties, conditions, limitations, and notices. TI is not responsible or liable for
such altered documentation. Information of third parties may be subject to additional restrictions.
Resale of TI components or services with statements different from or beyond the parameters stated by TI for that component or
service voids all express and any implied warranties for the associated TI component or service and is an unfair and deceptive
business practice. TI is not responsible or liable for any such statements.
Buyer acknowledges and agrees that it is solely responsible for compliance with all legal, regulatory and safety-related require-
ments concerning its products, and any use of TI components in its applications, notwithstanding any applications-related infor-
mation or support that may be provided by TI. Buyer represents and agrees that it has all the necessary expertise to create and
implement safeguards which anticipate dangerous consequences of failures, monitor failures and their consequences, lessen
the likelihood of failures that might cause harm and take appropriate remedial actions. Buyer will fully indemnify TI and its
representatives against any damages arising out of the use of any TI components in safety-critical applications.
In some cases, TI components may be promoted specifically to facilitate safety-related applications. With such components, TI’s
goal is to help enable customers to design and create their own end-product solutions that meet applicable functional safety
standards and requirements. Nonetheless, such components are subject to these terms.
No TI components are authorized for use in FDA Class III (or similar life-critical medical equipment) unless authorized officers of
the parties have executed a special agreement specifically governing such use.
Only those TI components which TI has specifically designated as military grade or “enhanced plastic” are designed and intended
for use in military/aerospace applications or environments. Buyer acknowledges and agrees that any military or aerospace use
of TI components which have not been so designated is solely at the Buyer's risk, and that Buyer is solely responsible for
compliance with all legal and regulatory requirements in connection with such use.
TI has specifically designated certain components as meeting ISO/TS16949 requirements, mainly for automotive use. In any
case of use of non-designated products, TI will not be responsible for any failure to meet ISO/TS16949.
Mailing Address: Texas Instruments, Post Office Box 655303 Dallas, Texas 75265
Copyright © 2014, Texas Instruments Incorporated
Products Applications
Audio www.ti.com/audio Automotive and Transportation www.ti.com/automotive
Amplifiers amplifier.ti.com Communications and Telecom www.ti.com/communications
Data Converters dataconverter.ti.com Computers and Peripherals www.ti.com/computers
DLP® Products www.dlp.com Consumer Electronics www.ti.com/consumer-apps
DSP dsp.ti.com Energy and Lighting www.ti.com/energy
Clocks and Timers www.ti.com/clocks Industrial www.ti.com/industrial
Interface interface.ti.com Medical www.ti.com/medical
Logic logic.ti.com Security www.ti.com/security
Power Mgmt power.ti.com Space, Avionics and Defense www.ti.com/space-avionics-defense
Microcontrollers microcontroller.ti.com Video & Imaging www.ti.com/video
RFID www.ti-rfid.com
OMAP Mobile Processors www.ti.com/omap TI E2E Community e2e.ti.com
Wireless Connectivity www.ti.com/wirelessconnectivity

Navigation menu