EE-6314 RTOS – TM4C123GH6PM Course Project

This repository contains a small real-time operating system (RTOS) written in C for the TM4C123GH6PM (ARM Cortex-M4F) microcontroller. It was developed as part of the EE-6314 Real-Time Operating Systems course and is designed as a teaching / learning kernel rather than a production RTOS.

The project demonstrates:

• A cooperative + preemptive, multi-threaded RTOS
• Priority-based scheduling with optional round-robin
• Priority inheritance to mitigate priority inversion
• Counting semaphores with blocking wait/notify
• Thread sleep / delay and deletion
• A UART-based shell for inspecting and controlling the system in real time

---

Features

Kernel and Scheduling

• Multi-threaded kernel with a fixed maximum number of tasks (see MAX_TASKS in 03_rtos.c).
• Priority scheduling with configurable priorities per thread.
• Round-robin scheduling option when priority scheduling is disabled.
• Preemptive and cooperative modes:
  • Preemptive context switching driven by the SysTick timer.
  • Cooperative mode via explicit yield calls.
• Priority inheritance to avoid unbounded priority inversion when threads contend for shared resources.
• SVC-based API for system calls:
  • YIELD
  • SLEEP
  • WAIT
  • POST
  • DELETE_THREAD

Synchronization

• Semaphores implemented in software:
  • Configurable initial count.
  • Internal wait queues for blocked threads.
  • Example semaphores: keyPressed, keyReleased, flashReq, resource (see main).

Demo Tasks

The RTOS starts several example tasks that exercise the scheduler and synchronization primitives, including:

• flash4Hz – toggles LEDs at a fixed frequency.
• oneshot – demonstrates one-time, delayed behavior.
• lengthyFn / partOfLengthyFn – simulate long-running CPU-bound work.
• important – high-priority work used to illustrate priority inversion and inheritance.
• uncooperative – a misbehaving task that does not yield voluntarily.
• readKeys / debounce – simple input handling.
• shell – interactive command-line interface over UART.

These tasks are created in main() via createThread() with different priorities to show scheduling behavior.

UART Shell

A simple UART-based shell runs as its own thread and allows you to inspect and interact with the RTOS at runtime.

Typical commands (parsed in parseshell() and handled in shell()) include:

• help
  Show a list of supported commands.
• pi on / pi off
  Enable or disable priority inheritance.
• priority on / rr
  Switch between priority scheduling and round-robin.
• preempt on / preempt off
  Toggle preemption vs cooperative scheduling.
• pidof <taskname>
  Print the PID of a named task.
• kill <pid>
  Terminate a running thread by PID.
• ps
  Show process status, including name, PID, priority, and CPU usage.
• ipcs
  Display semaphore information (counts, owners, waiters).
• history
  Print the last few commands entered.

The shell also supports a simple command history (! to repeat the previous command) and an “admin”-style prompt.

---

Hardware & Software Requirements

• Microcontroller: TM4C123GH6PM (e.g., TI Tiva C Series LaunchPad TM4C123GXL).
• Toolchain / IDE:
  • Texas Instruments Code Composer Studio (CCS), or
  • Any ARM Cortex-M4F-capable GCC toolchain with support for TM4C123GH6PM.
• Device support: TI’s device header tm4c123gh6pm.h and associated startup code / linker script (provided by TivaWare or CCS).

---

Repository Layout

• 03_rtos.c
  Main RTOS implementation, demo tasks, hardware initialization (clocks, GPIO, UART, SysTick), scheduler, semaphores, and shell.
• 03_tm4c123gh6pm_startup_ccs.c
  TI-provided startup code and interrupt vector table for TM4C123GH6PM using CCS.
• tm4c123gh6pm.cmd
  Linker command file specifying memory regions and sections.
• README.md
  Project documentation (this file).

---

Building and Running

1. Using Code Composer Studio (recommended)

1. Create a new CCS ARM Cortex-M4F project for the TM4C123GH6PM device.
2. Add the following source files to the project:
   • 03_rtos.c
   • 03_tm4c123gh6pm_startup_ccs.c
3. Use tm4c123gh6pm.cmd as the project’s linker command file.
4. Make sure the project is configured to use the device support files that provide tm4c123gh6pm.h.
5. Build the project, connect your TM4C123GXL LaunchPad, and load the program.

2. Serial Terminal

1. Connect a USB cable to the LaunchPad’s debug / USB interface.
2. Open a serial terminal (PuTTY, TeraTerm, minicom, etc.).
3. Configure the terminal for:
   • 115200 baud
   • 8 data bits
   • No parity
   • 1 stop bit (8-N-1)
4. Reset the board. You should see a banner from the shell and can start entering commands like help, ps, ipcs, etc.

---

Notes and Limitations

• This RTOS is designed for educational purposes and does not aim to be a full-featured production kernel.
• The number of tasks, semaphores, and queue sizes are fixed at compile time (MAX_TASKS, MAX_SEMAPHORES, MAX_QUEUE_SIZE).
• Only a single core (Cortex-M4F) is supported; there is no SMP support.
• Error handling is minimal; invalid configurations may cause assertions or undefined behavior.

---

Future Improvements

Possible extensions and clean-ups you could experiment with:

• Split the code into modules (kernel, hardware drivers, shell, demo tasks).
• Add Doxygen comments and generate API documentation.
• Implement message queues / mailboxes.
• Add more robust error handling and debug hooks.
• Port the kernel to other Cortex-M boards (e.g., STM32 Nucleo) by replacing the low-level hardware initialization layer.

---

If you are reading this as part of coursework, feel free to use the code to explore how a small RTOS is structured, experiment with different scheduling policies, and extend the shell with your own commands.