1. ENTC-489 Embedded Real Time Software Development Embedded Real Time Software Development Week 3 Sharing Nicely Week 3 - Sharing Nicely 1

2. ENTC-489 Embedded Real Time Software Development Today’s Agenda Review Homework Assignment New Kernel Concepts – Semaphores – Deadlocks – Priority Inversion – Mutexes Preparation for homework assignment – UART Library modifications Week 3 - Sharing Nicely 2

3. ENTC-489 Embedded Real Time Software Development Review Homework Assignment Start with BlankOSProject Create a program that will: – Blink color LED alternating Red/Blue at 1Hz – Blink yellow (on BOOSTXL-SENSEHUB) at 2Hz Required Techniques – Program will have at least 1 task – Timing will be performed with kernel calls only Week 3 - Sharing Nicely 3

4. ENTC-489 Embedded Real Time Software Development Design How many tasks do we need? – 1 Task does it all Task runs every 250mS Task keeps track of the LED states and alters them each time it is run, 8 states required – 2 Tasks, one for the Red/Blue LED, one for the Yellow Yellow LED task runs every 250mS Red/Blue LED task runs every 500mS – 3 Instances of 1 task Task started with arguments for which LED, how long to wait to start flashing, and what frequency Week 3 - Sharing Nicely 4

5. ENTC-489 Embedded Real Time Software Development Design: 3 Instances, 1 Task As long as each Instance of a task has its own stack and a unique priority, we can run as many instances of the task as we wish. Week 3 - Sharing Nicely 5

6. ENTC-489 Embedded Real Time Software Development Initializing the Blink Parameters typedef enum LED_POS_ENUM { RED_LED, GREEN_LED, BLUE_LED, YELLOW_LED } led_t; typedef struct led_blink_s { INT8U prio; /*! Task priority number (our handle) */ led_t led_position; /*! Which LED will be blink? */ uint32_t start_delay; /*! number of mS to delay before first LED on state */ uint32_t blink_freq; /*! How fast, in milli Hz will be blink it? */ } led_data_t; static led_data_t blue_config = { /* priority, led, delay, freq */ BLUE_PRIO, BLUE_LED, 0, BLUE_RED_FREQ }; static led_data_t red_config = { /* priority, led, delay, freq */ RED_PRIO, RED_LED, RED_START_DELAY, BLUE_RED_FREQ }; static led_data_t yellow_config = { /* priority, led, delay, freq */ YELLOW_PRIO, YELLOW_LED, 0, YELLOW_FREQ }; Week 3 - Sharing Nicely 6

7. ENTC-489 Embedded Real Time Software Development Blink Task Part 1 void blink_task( void *parms ) { led_data_t info; uint32_t led_on, blink_delay; volatile uint32_t *led_port; /* using this intermidiate pointer so we only have to cast once */ info = *((led_data_t *)parms); /* get the address of the pin we will be using */ switch ( info.led_position ) { case RED_LED: led_on = RED_LED_PIN; led_port = &(LAUNCH_OUTPUT_DATA); break;... default: /* we don't know what to toggle, so we will stop the task here */ OSTaskSuspend(info.prio); break; } /* switch ( info->led_position ) */ Week 3 - Sharing Nicely 7

8. ENTC-489 Embedded Real Time Software Development Blink Task Part 2 /* compute the blink delay just once, so we don't have to do this * calculation over and over again. We get the frequency in milli Hz, and * compute a time delay that is half that to get our 50% duty cycle */ blink_delay = ((OS_TICKS_PER_SEC * MILLI_HZ_PER_HZ) / info.blink_freq) / 2L; /* delay before we turn the LED on, remeber start_delay is in milliseconds */ OSTimeDly((OS_TICKS_PER_SEC * info.start_delay) / (uint32_t)1000); *led_port = led_on; while (1) { /* Delay for 1/2 cycle */ OSTimeDly(blink_delay); /* toggle the LED */ *led_port ^= led_on; } /* while (1) */ } /* blink_task () */ Week 3 - Sharing Nicely 8

9. ENTC-489 Embedded Real Time Software Development Semaphores Term comes from railroad track signals for trains Locking / Synchronization mechanism Types – Binary (not directly supported) – Counting Week 3 - Sharing Nicely 9

10. ENTC-489 Embedded Real Time Software Development Binary Semaphore Value can be 1 or 0 0 – “used” or “not ready” != 0 – “free” or “available” OSSemPend() “Pends” until the semaphore is non-zero OSSemPost() – Increments the semaphore value OSSemPend() – Pauses until the semaphore value is > 0 – Decrements the semaphore value Week 3 - Sharing Nicely 10

11. ENTC-489 Embedded Real Time Software Development Semaphore Used to Lock a Resource... uart0_xmt_sem = OSSemCreate(1); // initialize to “available”... void uart_puts(char *outstr) { OSSemPend(uart0_xmt_sem, 0, &err); // wait for the uart while (*outstr != ‘\0’) // sent the string out { // assumes a FIFO uart_out_char(*outstr); outstr += 1; } OSSemPost(&uart0_xmt_sem); // release the uart } Week 3 - Sharing Nicely 11

12. ENTC-489 Embedded Real Time Software Development Semaphore Used to Synchronize... a2d_complete_sem = OSSemCreate(0); // initialize to “not ready”... uint16_t a2d_read(uint8_t channel) { uint16_t a2d_value; OSSemAccept(a2d_complete_sem): // make sure the semphore is “not ready” a2d_start_conversion(channel); // start conversion OSSemPend(a2d_complete_sem, 0, &err); // wait for completion a2d_value = read_a2d_conversion_reg(); return a2d_value; } void a2d_complete_irq(void) { OSIntEnter(); clear_interrupt(a2d); // clear the a2d interrupt OSSemPost(a2d_complete_sem); // signal that the value is ready OSIntExit(); } Week 3 - Sharing Nicely 12

13. ENTC-489 Embedded Real Time Software Development Counting Semaphore Serial Input with H/W Buffer... uart_ch_avail_sem = OSSemCreate(0); // initialize to “empty”... void read_command(char *cbuf) { while (1) { OSSemPend(uart_ch_avail_sem, 0, &err); // wait for a character *cbuf = get_char_fifo(); // get it out of the fifo *(cbuf+1) = ‘\0’; // terminate the string if (*cbuf == ‘\r’;) { return ; // finnished receiving a line of data } void uart_rx_irq(void) { OSIntEnter(); clear_interrupt(uart); // clear the uart rx interrupt OSSemPost(uart_ch_avail_sem); // post that there is a character in the fifo OSIntExit(); } Week 3 - Sharing Nicely 13

14. ENTC-489 Embedded Real Time Software Development Semaphore Calls OS_EVENT *OSSemCreate(INT16U count) – Returns pointer to the semaphore event block or (OS_EVENT *)0 if there create fails – count is the initial value of the semaphore void OSSemPend(OS_EVENT *pevent, INT16U timeout, INT8U *err) – pevent points to the semaphore event control block – timeout is the number of ticks to wait before giving up. 0 waits forever – *err is set to OS_ERR_NONE or indicates an error (such as a timeout) INT8U OSSemPost(OS_EVENT *pevent) – pevent points to the semaphore event control block – Return value is either OS_ERR_NONE or an error code Week 3 - Sharing Nicely 14

15. ENTC-489 Embedded Real Time Software Development Deadlocks Task A OSSemPend(SemA) SemA is available, no pause Task B Resumes Task B OSSemPend(SemB) Task B OSSemPend(SemA) SemA is not available, Task B pauses Task A Resumes Task A OSSemPend(SemB) SemB is not available, Task A pauses Task A & Task B never resume Week 3 - Sharing Nicely 15

16. ENTC-489 Embedded Real Time Software Development Preventing Deadlock Avoid multiple semaphores for tightly coupled resources (if there is no SemB you can’t have a dead lock) – e.g. async serial port receive and transmit resources. When multiple semaphores are required (rare) document clearly and always “Pend” in the same order Week 3 - Sharing Nicely 16

17. ENTC-489 Embedded Real Time Software Development Priority Inversion Low priority task obtains a semaphore While the low priority task has the semaphore a high priority task pends on the same semaphore Mid level tasks prevent the low priority task from completing its use of the semaphore High priority task is delayed waiting for several low priority tasks to complete Week 3 - Sharing Nicely 17

18. ENTC-489 Embedded Real Time Software Development Priority Inversion Week 3 - Sharing Nicely 18

19. ENTC-489 Embedded Real Time Software Development Fixing Priority Inversion Mutex Similar to a binary semaphore OSMutexPend() causes calling task to “own” the mutex until it calls OSMutexPost() If OSMutexPend() pauses AND the task owning the mutex is a lower priority than the waiting task, the OS temporarily raises the priority of the low priority task unit it calls OSMutexPost() Week 3 - Sharing Nicely 19

20. ENTC-489 Embedded Real Time Software Development Mutex Timing Week 3 - Sharing Nicely 20

21. ENTC-489 Embedded Real Time Software Development Mutex Calls OS_EVENT *OSMutexCreate(INT8U prio, INT8U *err) – Returns a pointer to the event control block of the created mutex or (OS_EVENT *)0 if an error occurred. – prio is the priority to set a low priority task if it owns the mutex when a higher priority task performs a pend – err is populated with OS_ERR_NONE or the error code encountered void OSMutexPend(OS_EVENT *pevent, INT16U timeout, INT8U *err) – pevent points to the semaphore event control block – timeout is the number of ticks to wait before giving up. 0 waits forever – *err is set to OS_ERR_NONE or indicates an error (such as a timeout) INT8U OSMutexPost(OS_EVENT *pevent) – pevent points to the semaphore event control block – Return value is either OS_ERR_NONE or an error code Week 3 - Sharing Nicely 21

22. ENTC-489 Embedded Real Time Software Development BREAK Week 3 - Sharing Nicely 22

23. ENTC-489 Embedded Real Time Software Development Homework Due 2/18/15 Start with previous assignment (Blinky with OS) – Read a character (ch) from the serial port – If ch == ‘!’ print “Howdy darn it” to the serial port – else print “Howdy” to the serial port – Must make the task that reads the character the highest priority task – Serial I/O must be interrupt driven and buffered – Must use at least one semaphore Week 3 - Sharing Nicely 23

24. ENTC-489 Embedded Real Time Software Development TivaWare Library Needs uartstdio.c, uartstdio.h Alter to use interrupt driven, buffered serial I/O Alter to use semaphore Mark all additions or deletions you make to library files e.g. – // **HMW** Code added to support green widgets Week 3 - Sharing Nicely 24

25. ENTC-489 Embedded Real Time Software Development Changes to uartstdio.h At top of file – #define UART_BUFFERED This causes library conditional compilation to use buffered I/O Somewhere – includes or declarations needed to support semaphore signaling from library to your application code Week 3 - Sharing Nicely 25

26. ENTC-489 Embedded Real Time Software Development Changes to uartstdio.c At top of file change: – FROM: #include “driverlib/uartstdio.h” – TO: #include “uartstdio.h” UARTStdioConfig() – Create your semaphore while you are initializing everything else for the I/O port UARTStdioIntHandler() – Post to semaphore each time a new character is placed in the RX buffer – Don’t forget OSIntEnter() and OSIntExit() Week 3 - Sharing Nicely 26

27. ENTC-489 Embedded Real Time Software Development Enable UART on LaunchPad Insert UART0 interrupt handler, UARTStdioIntHandler() in the vector table Enable I/O pins and UART module (GPIOA and UART0) Set GPIO A0 and A1 as UART I/O Pins – Must do both a PinConfigure and PinTypeUART Set BAUD rate – use UARTStdioConfig() Enable the UART interrupts – ROM_IntEnable(INT_UART0) – ROM_UARTIntEnable(UART0_BASE, UART_INT_RX | UART_INT_RT) – ROM_IntMasterEnable() Turn off automatic echo (on by default for uartstdio functions Week 3 - Sharing Nicely 27

28. ENTC-489 Embedded Real Time Software Development Howdy Task Architecture Week 3 - Sharing Nicely 28

29. ENTC-489 Embedded Real Time Software Development Doxygen Doxygen provides the ability to create standalone documentation for a program by including specially formatted comments in the source. Believe it or not, documenting your design often is helpful when designing and debugging. Writing out your intent in English helps you verify that the code does what you meant. Week 3 - Sharing Nicely 29

30. ENTC-489 Embedded Real Time Software Development Doxygen Comment Blocks Comments blocks that will be processed by Doxygen: /// doxystuff //! Doxystuff /*! Doxystuff */ /** Doxystuff */ Comment blocks ignored by Doxygen: // stuff /**! Stuff */ /************************** * Stuff */ Week 3 - Sharing Nicely 30

31. ENTC-489 Embedded Real Time Software Development Comment Blocks Describe What is Below /*! \brief This is the brief description of the function * * This is a more verbose description of the function and can go * on for several lines. It is separated from the brief * description above by one or more blank comment lines (the * leading ‘*’ is ignored. Paragraphs are similarly created by * leaving a blank line. The description ends when the comment * block ends, or when another special tag is encountered like * this: * \param iters Pass the number of iterations in this parameter * \return uint32_t Returns the value of pi after parm1 iterations */ uint32_t bake_pi(uint16_t iters) {... } Week 3 - Sharing Nicely 31

32. ENTC-489 Embedded Real Time Software Development In-line Documentation #define MYVAR (3) /*!< My favorite variable */ enum colors { RED, /**< Color similar to pale maroon */ GREEN, /**< Color similar to grass */ BLUE /**< Color that is similar to the sky. also similar to the deep sea. */ }; void log_error( uint8_t num, /**< Error number being reported */ uint8_t severity, /**< Severity level of the error */ char *context /**< String providing additional details */ ) {... } Week 3 - Sharing Nicely 32

33. ENTC-489 Embedded Real Time Software Development Tags in Comments /*! \mainpage The Title For This Program * The information used in this comment is * placed on the front page of the doxygen created web * site. This comment can be used to explain your * code for the entire project at a high level. * * You can refer to other documented elements by using the * \ref barf tag (in this case refers to the variable, * structure or something else named “barf”. If you * write a function name like thisfunc() it will * automatically generate a link to that function. */ Week 3 - Sharing Nicely 33

34. ENTC-489 Embedded Real Time Software Development Tags for Grouping Similar Stuff /*! \addtogroup groupname * the rest of the comment creates a description of the * group. All the documentation between the open at-curley * and the closing at-curley is included in groupname. * @{ */... /*! @} */ Week 3 - Sharing Nicely 34

35. ENTC-489 Embedded Real Time Software Development Tags for Documenting Functions \param varname documents the parameter varname \return description of the return value \attention creates an ATTENTION entry in the function doc \brief creates a brief description for the function \note creates a NOTE entry in the function documentation \see creates a SEE ALSO entry for the function doc \warning creates a WARNING entry in the function doc Week 3 - Sharing Nicely 35

36. ENTC-489 Embedded Real Time Software Development Other handy tags \def DEFNAME documents #define DEFNAME \enum enumname documents enum enumname {…}; \struct structname documents struct structname {…}; \typedef typename documents typename \union unionname documents union unionname {…}; \var varname documents variable varname \bug adds a bug report, which is searchable by file location \todo adds a todo list, which is searchable by file location Week 3 - Sharing Nicely 36