Zephyr applications typically interact with hardware through standardized subsystem APIs rather than accessing registers directly or relying on vendor-specific hardware abstraction layers (HALs). This hardware abstraction is provided by Zephyr’s device driver model and devicetree system: devicetree describes the hardware independently of the application, while the build system selects and configures the appropriate drivers automatically.

PendSV (Pendable Service) Exception

• Used by the RTOS to perform deferred context switches between tasks
• Usually pended by the SysTick handler or when a task explicitly yields
• Configured at the lowest interrupt priority so that context switching occurs only after higher-priority interrupt handlers have finished
• Triggered by software through the NVIC’s Interrupt Control and State Register, not directly by a peripheral

SVC (Supervisor Call) Exception

• Synchronously triggered by executing an SVC instruction
• Used to request privileged operating-system services
• In FreeRTOS Cortex-M ports, SVC 0 is executed by vPortStartFirstTask() to start the scheduler and restore the first task’s context
• In those ports, this startup call normally occurs only once; other ports, particularly MPU-enabled ones, may use SVC for additional services

SysTick Timer Exception

• Provides the FreeRTOS timebase at configTICK_RATE_HZ
• Runs at the lowest interrupt priority in typical Cortex-M ports
• Updates delays and timeouts on every tick
• Pends PendSV when task rescheduling is needed

Scheduling and Exception Handling on Cortex-M

STM32/Cortex-M Interrupt Priorities

On STM32 microcontrollers, FreeRTOS configures PendSV and SysTick at the lowest NVIC priority using configKERNEL_INTERRUPT_PRIORITY. Interrupts with a numeric priority value equal to or greater than configMAX_SYSCALL_INTERRUPT_PRIORITY may call only FromISR() APIs, while higher-priority interrupts with smaller numeric values must not call FreeRTOS APIs. The NVIC also supports nesting, allowing higher-priority interrupts to preempt lower-priority ones.

// FreeRTOSConfig.h
#define vPortSVCHandler  SVC_Handler
#define xPortPendSVHandler 	PendSV_Handler

#ifdef __NVIC_PRIO_BITS
	#define configPRIO_BITS  __NVIC_PRIO_BITS
#else
	#define configPRIO_BITS  4
#endif

// Lowest priority allowed in priority-setting functions
#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY  15 

// Priorities 0–4: High-priority ISRs; must not call FreeRTOS APIs
// Priorities 5–15: RTOS-aware ISRs; may call only xxxFromISR() APIs
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY  5  

// FreeRTOSConfig.h
#define vPortSVCHandler  SVC_Handler
#define xPortPendSVHandler 	PendSV_Handler

#ifdef __NVIC_PRIO_BITS
	#define configPRIO_BITS  __NVIC_PRIO_BITS
#else
	#define configPRIO_BITS  4
#endif

// Lowest priority allowed in priority-setting functions
#define configLIBRARY_LOWEST_INTERRUPT_PRIORITY  15 

// Priorities 0–4: High-priority ISRs; must not call FreeRTOS APIs
// Priorities 5–15: RTOS-aware ISRs; may call only xxxFromISR() APIs
#define configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY  5  

TI C2000 Microcontrollers (TMS320F2837xx, TMS320F2838xx)

• Embedded Coder Version 26.1 (R2026a)
• TI Code Composer Studio 12.8.1
• TI C2000 Code Generation Tools (compiler) 22.6.1
• TI C2000Ware 5_04_00_00
• TI ARM Code Generation Tools (compiler) 20.2.7

>> c2000setup
>> c2000lib

>> c2000setup
>> c2000lib

Example: LED Blinking and Button-Controlled LED

• Button: GPIO10
• Red LED: GPIO41
• Blue LED: GPIO58

Example: Real-time Control Module for HIL

Reference

[1] C2000 Microcontroller Blockset
[2] C2000 Microcontroller Blockset – Examples
[3] C2000 Microcontroller Blockset – Videos
[4] C2000 Microcontroller Blockset – Blocks
[5] Get Started with C2000 Microcontroller Blockset
[6] Applications
[7] Peripherals
[8] Multiprocessor Architecture Modeling
[9] Connected IO Simulation
[10] Signal Monitoring and Parameter Tuning
[11] Deployment and Validation

Zephyr Devicetree: Separating Hardware from Application Logic

Zephyr uses devicetree to describe hardware separately from application logic. Peripheral addresses, interrupt numbers, pin assignments, and other hardware-specific details are defined at build time rather than hardcoded in source code.

The devicetree is then processed into compile-time information that drivers and applications can access through generated macros. This separation improves portability and maintainability, allowing the same application code to run on different boards and SoCs while board-specific hardware configuration is selected during the build process.

With devicetree, each vendor describes hardware in its own .dts file. The hardware description differs, but the application code does not change time. This approach is lightweight and efficient for embedded systems.

# Vendor A
uart0: uart@40021000 {
  compatible = "vendora,uart";
  reg = <0x40021000 0x400>;
  status = "okay";
};

# Vendor B
uart0: uart@50003000 {
  compatible = "vendorb,uart";
  reg = <0x50003000 0x400>;
  status = "okay";
};

# Vendor A
uart0: uart@40021000 {
  compatible = "vendora,uart";
  reg = <0x40021000 0x400>;
  status = "okay";
};

# Vendor B
uart0: uart@50003000 {
  compatible = "vendorb,uart";
  reg = <0x50003000 0x400>;
  status = "okay";
};

A Zephyr board typically does not describe all hardware in a single .dts file.

The main board devicetree file: zephyr/boards/<vendor>/<board>/<board>.dts
usually includes one or more .dtsi files that provide shared hardware descriptions, such as:

• SoC configuration
• Pin control definitions
• Shared peripherals
• Common board-level hardware features

This layered structure avoids duplication and allows related boards to reuse the same SoC and hardware definitions. During the build, the .dts, included .dtsi files, and any applicable overlays are merged into a final resolved devicetree: build/<project_name>/zephyr/zephyr.dts

This generated file represents the final hardware description used by the build system and is useful for verifying the effective configuration and debugging devicetree-related issues.

Devicetree Overlays

Board devicetree files define the default hardware configuration for a board. However, applications often need to enable additional peripherals, modify existing properties, or describe application-specific hardware without changing the original board files. Devicetree overlays provide a flexible way to extend or override the board’s default hardware configuration at build time while keeping the base board definition unchanged.

Alternatively, an app.overlay file can be created in the application root directory. If both app.overlay and boards/<board_name>.overlay are present, Zephyr uses the board-specific overlay for the selected board.

└── apps/  
      └── project
             ├── CMakeLists.txt
             ├── Kconfig
             ├── prj.conf
             ├── extra.conf
             ├── app.overlay
             └── boards/
                  ├── <board_name>.conf 
                  └── <board_name>.overlay
             └── src/
                  └── main.c

└── apps/  
      └── project
             ├── CMakeLists.txt
             ├── Kconfig
             ├── prj.conf
             ├── extra.conf
             ├── app.overlay
             └── boards/
                  ├── <board_name>.conf 
                  └── <board_name>.overlay
             └── src/
                  └── main.c

# app.overlay
&i2c1 {
  status = "okay";
  mpu6050: mpu6050@68 {
    compatible = "invensense,mpu6050";
    reg = <0x68>;
  };
};

# boards/stm32f4_disco.overlay
/ {
  aliases {
    led0 = &red_led_5;
    led1 = &blue_led_6;
    led2 = &green_led_4;
    led3 = &orange_led_3;
		sw0 = &user_button;
  };
};

&adc1{
  pinctrl-0 = <&adc1_in1_pa1>;
  pinctrl-names = "default";
	st,adc-prescaler = <4>;
	status = "okay";
};

# app.overlay
&i2c1 {
  status = "okay";
  mpu6050: mpu6050@68 {
    compatible = "invensense,mpu6050";
    reg = <0x68>;
  };
};

# boards/stm32f4_disco.overlay
/ {
  aliases {
    led0 = &red_led_5;
    led1 = &blue_led_6;
    led2 = &green_led_4;
    led3 = &orange_led_3;
		sw0 = &user_button;
  };
};

&adc1{
  pinctrl-0 = <&adc1_in1_pa1>;
  pinctrl-names = "default";
	st,adc-prescaler = <4>;
	status = "okay";
};

Devicetree overlays do not replace the board’s devicetree source file. Instead, they are merged with the base devicetree to extend or override its configuration.

Because overlays are applied during the build process, they can:

• Override existing property values
• Change a node’s status
• Add new nodes or properties

The final devicetree is generated entirely at build time. Devicetree overlays do not provide runtime hardware reconfiguration.

Devicetree Build Flow: Overlays, zephyr.dts, and Generated Headers

The build process is:

• Devicetree source files and overlays are merged into a single hardware description
• The merged result is written to zephyr.dts
• Zephyr generates devicetree_generated.h from the final devicetree

The zephyr.dts file represents the complete hardware description used for the build after all board definitions and overlays have been applied. It is especially useful for verifying the final configuration and debugging devicetree-related issues.

The devicetree_generated.h file contains C macros generated from the final merged devicetree. These macros are automatically made available to the application and drivers during compilation.

They allow source code to:

• Reference devicetree nodes
• Read properties defined in the devicetree
• Check whether a node or device is enabled
• Access hardware information such as addresses, interrupts, GPIOs, and other configuration data

Application code and drivers do not parse .dts files directly. Instead, they use the generated devicetree macros and helper APIs provided by Zephyr.

└── build/project/zephyr/
      ├── zephyr.dts (merged Devicetree output)
      └── include/generated/zephyr/
              └── devicetree_generated.h (Devicetree macros)

└── build/project/zephyr/
      ├── zephyr.dts (merged Devicetree output)
      └── include/generated/zephyr/
              └── devicetree_generated.h (Devicetree macros)

Modifying Devicetree Nodes with Overlays

Board devicetree files define the default hardware configuration for most peripherals and devices. However, applications often need to enable a disabled peripheral, modify an existing property, or add application-specific hardware settings without changing the original board definition. Devicetree overlays provide a clean way to extend or override only the required parts of the hardware description.

# stm32f4.dtsi
adc1: adc@40012000 {
  compatible = "st,stm32f4-adc", "st,stm32-adc";
	reg = <0x40012000 0x400>;
	clocks = <&rcc STM32_CLOCK(APB2, 8)>;
	clock-names = "adcx";
	interrupts = <18 0>;
	#io-channel-cells = <1>;
	st,adc-resolutions = <12 10 8 6>;
	sampling-times = <3 15 28 56 84 112 144 480>;
	st,adc-clock-source = "SYNC";
	st,adc-sequencer = "programmable";
	st,adc-oversampler = "none";
	st,adc-internal-regulator = "none";
	st,adc-has-injected-support;
	status = "disabled";
};

# stm32f4_disco.dts
&adc1 {
	pinctrl-0 = <&adc1_in1_pa1 &adc1_in6_pa6>;
	pinctrl-names = "default"; # Index 0 corresponds to "default"
	st,adc-prescaler = <2>;
	status = "okay"; # Enable this hardware peripheral for use by Zephyr
};

# stm32f4.dtsi
adc1: adc@40012000 {
  compatible = "st,stm32f4-adc", "st,stm32-adc";
	reg = <0x40012000 0x400>;
	clocks = <&rcc STM32_CLOCK(APB2, 8)>;
	clock-names = "adcx";
	interrupts = <18 0>;
	#io-channel-cells = <1>;
	st,adc-resolutions = <12 10 8 6>;
	sampling-times = <3 15 28 56 84 112 144 480>;
	st,adc-clock-source = "SYNC";
	st,adc-sequencer = "programmable";
	st,adc-oversampler = "none";
	st,adc-internal-regulator = "none";
	st,adc-has-injected-support;
	status = "disabled";
};

# stm32f4_disco.dts
&adc1 {
	pinctrl-0 = <&adc1_in1_pa1 &adc1_in6_pa6>;
	pinctrl-names = "default"; # Index 0 corresponds to "default"
	st,adc-prescaler = <2>;
	status = "okay"; # Enable this hardware peripheral for use by Zephyr
};

Enable STM32 ADC1, configure PA1 as ADC1 channel 1 and PA6 as ADC1 channel 6, use these pins as ADC1’s default pin configuration, and configure the STM32-specific ADC clock prescaler.

pinctrl-0 = <&adc1_in1_pa1 &adc1_in6_pa6>;

# PA1 -> ADC1_IN1
adc1_in1_pa1
     │   │
     │   └── PA1
     └────── ADC1 input channel 1

# PA6 -> ADC1_IN6
adc1_in6_pa6
     │   │
     │   └── PA6
     └────── ADC1 input channel 6     

pinctrl-0 = <&adc1_in1_pa1 &adc1_in6_pa6>;

# PA1 -> ADC1_IN1
adc1_in1_pa1
     │   │
     │   └── PA1
     └────── ADC1 input channel 1

# PA6 -> ADC1_IN6
adc1_in6_pa6
     │   │
     │   └── PA6
     └────── ADC1 input channel 6     

boards/stm32f4_disco.overlay

This overlay modifies the existing adc1 node for the stm32f4_disco board and then defines one ADC channel configuration for the application.

&adc1 {
  # Overrides the board's default pinctrl list
  pinctrl-0 = <&adc1_in1_pa1>;
  # Reconfigures an ST-specific ADC clock prescaler
  st,adc-prescaler = <4>;
  # Enables ADC1 
  status = "okay"; 
	
	# Creates a child node describing an ADC channel configuration
	channel@1 {
		reg = <1>; # ADC channel 3
		# Sets the ADC gain to 1
		zephyr,gain = "ADC_GAIN_1";
		# Selects the ADC reference configuration used by Zephyr 
		zephyr,reference = "ADC_REF_INTERNAL";
		# Sets the ADC sample/acquisition time
		zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
		# Perform the ADC conversion using 12-bit resolution 
		zephyr,resolution = <12>;
	}; 
};

&adc1 {
  # Overrides the board's default pinctrl list
  pinctrl-0 = <&adc1_in1_pa1>;
  # Reconfigures an ST-specific ADC clock prescaler
  st,adc-prescaler = <4>;
  # Enables ADC1 
  status = "okay"; 
	
	# Creates a child node describing an ADC channel configuration
	channel@1 {
		reg = <1>; # ADC channel 3
		# Sets the ADC gain to 1
		zephyr,gain = "ADC_GAIN_1";
		# Selects the ADC reference configuration used by Zephyr 
		zephyr,reference = "ADC_REF_INTERNAL";
		# Sets the ADC sample/acquisition time
		zephyr,acquisition-time = <ADC_ACQ_TIME_DEFAULT>;
		# Perform the ADC conversion using 12-bit resolution 
		zephyr,resolution = <12>;
	}; 
};

Perform a pristine rebuild and inspect zephyr.dts

└── build/project/zephyr/
      ├── zephyr.dts (merged Devicetree output)
      └── include/generated/zephyr/
              └── devicetree_generated.h (Devicetree macros)

└── build/project/zephyr/
      ├── zephyr.dts (merged Devicetree output)
      └── include/generated/zephyr/
              └── devicetree_generated.h (Devicetree macros)

Zephyr Devicetree Structure: ADC Configuration Example

• adc1 is the node label. It allows references using &adc1
• adc@42028000 is the node name and unit address

Reference

[1] Zephyr Devicetree
[2] Zephyr Project Documentation – Devicetree syntax and structure

Zephyr uses Kconfig as its primary configuration system to control which features are enabled, how subsystems behave, and how the final firmware image is built. Instead of hardcoding feature choices into source files, developers can use Kconfig to manage configuration in a structured and scalable way, making it easier to adapt applications across boards and use cases. Zephyr applications often need to enable features such as logging, networking, or debugging support while keeping unnecessary code out of the final firmware.

• Each feature, such as a driver, network stack, or logging option, is controlled by a CONFIG_ setting.
• These CONFIG_ settings are enabled or configured in the prj.conf file

The file prj.conf defines project-specific configuration options by setting Kconfig symbols that enable, disable, or customize Zephyr features, drivers, subsystems, and build settings.

STM32xx SoC Support Directory

Provides the common SoC-level support used by STM32xx-based boards, including Kconfig definitions and defaults, CMake build integration, early SoC initialization, shared headers, and power-management or power-off functionality. It contains code and configuration that are specific to the STM32xx family but shared across multiple STM32xx boards.

└── zephyr/
      └── soc/st/stm32/
              └── stm32f4x/
                     ├── CMakeLists.txt
                     ├── Kconfig
                     ├── Kconfig.defconfig
                     ├── Kconfig.soc
                     ├── power.c
                     ├── poweroff.c
                     ├── soc.c
                     └── soc.h
              └── stm32f7x/
                     ├── CMakeLists.txt
                     ├── Kconfig
                     ├── Kconfig.defconfig
                     ├── Kconfig.defconfig.stm32f765xx                  
                     ├── Kconfig.defconfig.stm32f767xx
                     ├── Kconfig.defconfig.stm32f769xx
                     ├── Kconfig.soc
                     ├── soc.c
                     └── soc.h
              └── stm32h7x/
                     ├── CMakeLists.txt
                     ├── Kconfig
                     ├── Kconfig.defconfig
                     ├── Kconfig
                     ├── Kconfig.defconfig.stm32h745xx                  
                     ├── Kconfig.defconfig.stm32h747xx
                     ├── Kconfig.defconfig.stm32h755xx
                     ├── Kconfig.defconfig.stm32h757xx
                     ├── Kconfig.soc
                     ├── mpu_regions.c
                     ├── sections.ld
                     ├── soc_m4.c
                     ├── soc_m7.c
                     └── soc.h                                                

└── zephyr/
      └── soc/st/stm32/
              └── stm32f4x/
                     ├── CMakeLists.txt
                     ├── Kconfig
                     ├── Kconfig.defconfig
                     ├── Kconfig.soc
                     ├── power.c
                     ├── poweroff.c
                     ├── soc.c
                     └── soc.h
              └── stm32f7x/
                     ├── CMakeLists.txt
                     ├── Kconfig
                     ├── Kconfig.defconfig
                     ├── Kconfig.defconfig.stm32f765xx                  
                     ├── Kconfig.defconfig.stm32f767xx
                     ├── Kconfig.defconfig.stm32f769xx
                     ├── Kconfig.soc
                     ├── soc.c
                     └── soc.h
              └── stm32h7x/
                     ├── CMakeLists.txt
                     ├── Kconfig
                     ├── Kconfig.defconfig
                     ├── Kconfig
                     ├── Kconfig.defconfig.stm32h745xx                  
                     ├── Kconfig.defconfig.stm32h747xx
                     ├── Kconfig.defconfig.stm32h755xx
                     ├── Kconfig.defconfig.stm32h757xx
                     ├── Kconfig.soc
                     ├── mpu_regions.c
                     ├── sections.ld
                     ├── soc_m4.c
                     ├── soc_m7.c
                     └── soc.h                                                

Example of prj.conf

# GPIO
CONFIG_GPIO=y

# ADC
CONFIG_ADC=y

# I2C
CONFIG_I2C=y

# Serial / UART
CONFIG_SERIAL=y
CONFIG_UART_INTERRUPT_DRIVEN=y

# Console
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y
CONFIG_STDOUT_CONSOLE=y
CONFIG_PRINTK=y

# Logging
CONFIG_LOG=y
CONFIG_LOG_DEFAULT_LEVEL=3
CONFIG_LOG_MODE_DEFERRED=y
CONFIG_LOG_PROCESS_THREAD=y
CONFIG_ASSERT=y

# C Library
CONFIG_MINIMAL_LIBC=y
CONFIG_PICOLIBC=n
CONFIG_NEWLIB_LIBC=n

# Increase the main thread stack size
CONFIG_MAIN_STACK_SIZE=4096

# GPIO
CONFIG_GPIO=y

# ADC
CONFIG_ADC=y

# I2C
CONFIG_I2C=y

# Serial / UART
CONFIG_SERIAL=y
CONFIG_UART_INTERRUPT_DRIVEN=y

# Console
CONFIG_CONSOLE=y
CONFIG_UART_CONSOLE=y
CONFIG_STDOUT_CONSOLE=y
CONFIG_PRINTK=y

# Logging
CONFIG_LOG=y
CONFIG_LOG_DEFAULT_LEVEL=3
CONFIG_LOG_MODE_DEFERRED=y
CONFIG_LOG_PROCESS_THREAD=y
CONFIG_ASSERT=y

# C Library
CONFIG_MINIMAL_LIBC=y
CONFIG_PICOLIBC=n
CONFIG_NEWLIB_LIBC=n

# Increase the main thread stack size
CONFIG_MAIN_STACK_SIZE=4096

Zephyr Application Directory

• CMakeLists.txt: Connects the project to Zephyr’s build system
• Kconfig: Defines application options, their types, defaults, and dependencies
• prj.conf: Configures application, Zephyr, and module features by setting option values
• extra.conf: Optional Kconfig configuration fragment used to add or override settings in prj.conf for a particular build
• <board_name>.conf: Board-specific Kconfig settings
• <board_name>.overlay: Board-specific Devicetree hardware changes

└── apps/  
      └── project_1
             ├── CMakeLists.txt
             ├── Kconfig
             ├── prj.conf
             ├── extra_1.conf
             ├── extra_2.conf
             └── boards/
                  ├── <board_name_1>.conf 
                  ├── <board_name_1>.overlay
                  ├── <board_name_2>.conf
                  └── <board_name_2>.overlay
             └── src/
                  └── main.c

└── apps/  
      └── project_1
             ├── CMakeLists.txt
             ├── Kconfig
             ├── prj.conf
             ├── extra_1.conf
             ├── extra_2.conf
             └── boards/
                  ├── <board_name_1>.conf 
                  ├── <board_name_1>.overlay
                  ├── <board_name_2>.conf
                  └── <board_name_2>.overlay
             └── src/
                  └── main.c

Zephyr Kconfig Configuration Flow

When a Zephyr application is built, the build system first runs the Kconfig configuration phase. During this phase:

• Load Kconfig definitions from Zephyr, modules, and the application
• Load board defaults from <BOARD>_defconfig
• Merge application settings from prj.conf, followed by additional <FRAGMENT>.conf fragments
• Resolve Kconfig defaults, dependencies, and symbol selections
• Save the resolved configuration to .config
• Generate autoconf.h with configuration macros used during compilation

# The resulting configuration is stored in:
<build-dir>/zephyr/.config

# The build system also generates:
<build-dir>/zephyr/include/generated/zephyr/autoconf.h

# The resulting configuration is stored in:
<build-dir>/zephyr/.config

# The build system also generates:
<build-dir>/zephyr/include/generated/zephyr/autoconf.h

Reference

[1] Zephyr Configuration System (Kconfig)
[2] Zephyr: Setting Kconfig Configuration Values

FreeRTOS on TI C2000 C28x vs. STM32 MCUs

Stack Differences

On TI C2000, FreeRTOS-allocated memory begins on a boundary aligned to two C28x address units, equivalent to four conventional bytes. On STM32, FreeRTOS-allocated memory begins on an 8-byte boundary, meaning its starting address is a multiple of eight.

// TI C2000 C28x, portmacro.h
#define portBYTE_ALIGNMENT 2

// STM32, portmacro.h
#define portBYTE_ALIGNMENT 8

// TI C2000 C28x, portmacro.h
#define portBYTE_ALIGNMENT 2

// STM32, portmacro.h
#define portBYTE_ALIGNMENT 8

FreeRTOS Data Type Mapping for TI C2000 C28x MCU

Heap and Memory Differences

The C28 project explicitly declares ucHeap[] and places it in .freertosHeap. The STM32 project lets heap_4.c declare the heap internally in .bss.

The C28x stack pointer is more restricted than the Cortex-M stack pointer. C28x task stacks generally must reside in the lower, stack-addressable data-memory range. This is why C28x projects often explicitly place the FreeRTOS heap in a suitable RAM section:

With FPU32 enabled, C28x saves floating-point state on every task context switch, increasing task stack usage. Cortex-M4F typically uses lazy FPU stacking, saving extra floating-point registers only when needed.

On C28x, a request of 100 allocates 100 sixteen-bit addressable units because the smallest addressable unit is 16 bits. This corresponds to 200 conventional eight-bit bytes of physical storage. On STM32, a request of 100 allocates 100 standard eight-bit bytes, since memory is byte-addressable.

Interrupt Model

C2000 does not use NVIC or BASEPRI. It uses:

• INTM: global maskable-interrupt enable/disable bit
• IER: CPU interrupt enable register
• IFR: CPU interrupt flag register
• PIE: Peripheral Interrupt Expansion controller
• PIE: Peripheral Interrupt Expansion controller
CPU interrupt groups INT1 through INT14

The C28x port protects the kernel using the global INTM bit:

// portmacro.h
#define portDISABLE_INTERRUPTS() __asm(" setc INTM")
#define portENABLE_INTERRUPTS()  __asm(" clrc INTM")

// portmacro.h
#define portDISABLE_INTERRUPTS() __asm(" setc INTM")
#define portENABLE_INTERRUPTS()  __asm(" clrc INTM")

Therefore, during a FreeRTOS critical section:

INTM = 1 -> all normal maskable C28x interrupts are disabled
INTM = 0 -> normal maskable interrupts are allowed

INTM = 1 -> all normal maskable C28x interrupts are disabled
INTM = 0 -> normal maskable interrupts are allowed

Unlike STM32, C2000 FreeRTOS does not leave a class of high-priority maskable interrupts running. Consequently, it does not need a “maximum syscall interrupt priority” boundary.

Example: FreeRTOS Demo for F28377S Coreboard V1.3

FreeRTOS TI C2000 F28377S Demo Code

Protocols of the LwIP Stack

• IPv4 and IPv6 (Internet Protocol v4 and v6)
• TCP (Transmission Control Protocol)
• UDP (User Datagram Protocol)
• DNS (Domain Name Server)
• SNMP (Simple Network Management Protocol)
• DHCP (Dynamic Host Configuration Protocol)
• PPP (Point to Point Protocol)
• ARP (Address Resolution Protocol)
• ICMP (Internet Control Message Protocol)
• IGMP (Internet Group Management Protocol)

Protocol Files of LwIP Stack

• Application Layer: dhcp.c, dns.c
• Transport Layer: udp.c, tcp.c
• Internet Layer: ip.c
• Network Interface Layer: netif.c

Ethernet Controller Interface

1. The official LwIP core stack is hardware-independent and does not include MCU-specific Ethernet MAC/PHY drivers. Hardware-specific drivers are normally provided by the MCU vendor, SDK, BSP, or application.
2. For MCU integrations, such as STM32 projects generated by STM32CubeMX, a file named ethernetif.c provides the interface between the LwIP network stack and the underlying Ethernet hardware driver.
3. The ethernetif.c is essentially a hardware-abstraction/adaptation layer. It must be implemented or customized for the target MCU, Ethernet MAC, PHY, DMA configuration, and operating environment.
4. The main responsibility of ethernetif.c is to transfer Ethernet frames between LwIP and the low-level Ethernet driver:
   • Transmit: LwIP pbuf → ethernetif.c → Ethernet MAC/DMA driver → Ethernet hardware
   • Receive: Ethernet hardware → Ethernet MAC/DMA driver → ethernetif.c → LwIP pbuf
5. Typical functions implemented in ethernetif.c include:
   • low_level_init(): initializes the Ethernet interface and related hardware
   • low_level_output(): sends an Ethernet frame
   • low_level_input(): receives an Ethernet frame
   • ethernetif_input(): passes received packets to the LwIP stack
   • ethernetif_init(): initializes and registers the network interface

Buffer Management

1. A pbuf (packet buffer) is a core LwIP data structure used to store and manage network packet data.
2. A pbuf can either contain dynamically allocated packet data or reference packet data stored elsewhere, including RAM or ROM, depending on the pbuf type and allocation method.
3. A single packet may be divided across multiple pbuf structures linked together through the next pointer. This is called a pbuf chain.
4. Multiple packets can also be linked using the same next pointer mechanism, forming a packet queue. LwIP distinguishes packet boundaries using fields such as len and tot_len.
5. Important fields in struct pbuf include:
   • next: pointer to next pbuf in a pbuf chain
   • payload: pointer to packet data
   • len: number of data bytes stored in the current pbuf
   • tot_len: total number of bytes from the current pbuf to the end of the current packet
   • ref (on 4 bits): reference count that indicates the number of pointers that reference the pbuf. A pbuf can be released from memory only when its reference count is zero

Types of pbufs

PBUF_POOL
1. With PBUF_POOL, pbufs are allocated from a statically configured memory pool containing a fixed number of fixed-size buffers.
2. Each allocated pbuf contains both the pbuf structure and a payload buffer.
3. If the packet is larger than the payload capacity of a single pool buffer, LwIP allocates multiple pbufs and links them together to form a pbuf chain.
4. PBUF_POOL is commonly used for receiving Ethernet packets, where fast and predictable allocation is important.

PBUF_RAM
1. With PBUF_RAM, memory is dynamically allocated from LwIP’s heap.
2. The pbuf structure and its payload are normally allocated as one contiguous block of memory.
3. Unlike PBUF_POOL, a PBUF_RAM allocation normally creates a single pbuf large enough to hold the requested packet, rather than chaining multiple fixed-size pool buffers.
4. PBUF_RAM is commonly used when constructing or transmitting packets whose size is known at allocation time.

APIs for Managing pbufs

1. pbuf_alloc(): Allocates a new pbuf of the specified type and size. For PBUF_POOL, the result may be a chain of multiple pbufs.
2. pbuf_realloc(): Shrinks a pbuf or pbuf chain to a specified length. Despite its name, it cannot enlarge a pbuf. Any unused pbufs at the end of the chain are freed.
3. pbuf_ref(): Increments the reference count (ref) of a pbuf, indicating that another reference to the pbuf exists.
4. pbuf_free(): Decrements the reference count of a pbuf. If the reference count reaches 0, the pbuf is deallocated. For a chain, this process continues until a pbuf with a remaining nonzero reference count is encountered.
5. pbuf_clen(): Returns the number of individual pbufs in a pbuf chain.
6. pbuf_cat(): Concatenates two pbufs or pbuf chains. It does not increment the reference count of the tail chain; ownership of the caller’s tail reference is transferred to the resulting chain.
7. pbuf_chain(): Chains two pbufs or pbuf chains together and increments the reference count of the first pbuf in the tail chain, allowing the caller to retain its own reference to the tail.
8. pbuf_dechain(): Detaches the first pbuf from the remainder of a pbuf chain. The first pbuf becomes a standalone pbuf, and the function returns the remaining chain if it is still allocated.
9. pbuf_copy_partial(): Copies a specified number of bytes from a pbuf or pbuf chain, starting at a specified offset, into an application-provided buffer.
10. pbuf_take(): Copies application-provided data into an existing pbuf or pbuf chain. The destination pbuf must have sufficient capacity.
11. pbuf_coalesce(): Converts a chained pbuf into a single contiguous pbuf. If allocation fails, the original pbuf is returned unchanged.

Reference

[1] Light Weight Internet Protocol
[2] Embedded Ethernet Firmware Development Learning Path

Zephyr is an open-source, scalable, and secure real-time operating system (RTOS) designed for modern embedded and connected devices. It supports a wide range of hardware platforms, from small resource-constrained microcontrollers to more capable edge-computing systems.

• Kernel: It manages threads, scheduling, interrupts, synchronization, timing, and other system resources.
• Multithreading: Allows multiple threads to execute concurrently, enabling applications to handle several operations while maintaining responsiveness and real-time behavior.
• Memory Management: Provides mechanisms for efficient and predictable use of limited memory, including dynamic allocation, memory pools, stacks, and memory protection.

Zephyr Workspace and Project Directory

A Zephyr application is more than a set of source files. It exists within a structured workspace, integrates with a multi-stage build system, and depends on multiple repositories working together. In practice, developers often need to set up a workspace, organize application code, and manage dependencies while ensuring that builds remain reproducible across environments.

A West workspace is identified by the presence of the .west/ directory at its root. When a West command runs, it searches upward in the directory tree until it finds this directory, then performs all operations relative to that workspace root. Inside the workspace, multiple repositories coexist, including the Zephyr repository, which contains the kernel, subsystems, drivers, and build system. Applications are typically placed alongside the Zephyr repository rather than inside it, and a workspace may contain one or many applications.

A Zephyr workspace is defined by a manifest file that specifies which repositories are used, where they are fetched from, and how they are organized locally. The West manifest is a YAML file named west.yml. It describes the repositories (called projects in West terminology) that belong to a workspace. The manifest may live in different locations depending on the chosen workspace topology, but its purpose remains the same: to define the composition of the workspace.

• arch/: CPU architecture support
• boards/: Board definitions, Devicetree, Kconfig, and default settings
• cmake/: CMake build-system modules
• drivers/: Hardware drivers: GPIO, I2C, SPI, UART, ADC, sensors, etc
• include/: Public Zephyr API headers
• kernel/: Kernel: scheduler, threads, synchronization, timers
• samples/: Example and reference applications
• scripts/: Build, configuration, flashing, testing, and helper tools
• soc/: Vendor- and SoC-specific support
• subsys/: System services: logging, shell, networking, settings, etc
• tests/: Kernel, driver, subsystem, and API tests
• west.yml: Defines which repositories West uses and where to find them

zephyr-sdk-<version>/

zephyr_workspace/
     ├── .venv/
     └── .west/
           └── config
     └── bootloader/
           └── mcuboot/
     └── modules/
           └── hal/
                ├── cmsis/ 
                └── stm32/        
           └── lib/
                ├──cmsis-dsp/
                └──cmsis-nn/
           └── fs/
                ├── fatfs/
                └── littlefs/  
     └── zephyr/
           ├── arch/
           ├── boards/
           ├── cmake/
           ├── drivers/
           ├── include/
           ├── kernel/
           ├── samples/
           ├── scripts/
           ├── soc/
           ├── subsys/
           ├── tests/
           └── west.yml
     ├── tools/     
     └── apps/  
          ├── project_1
          └── project_2
     └── build/
          ├── project_1
          └── project_2            

zephyr-sdk-<version>/

zephyr_workspace/
     ├── .venv/
     └── .west/
           └── config
     └── bootloader/
           └── mcuboot/
     └── modules/
           └── hal/
                ├── cmsis/ 
                └── stm32/        
           └── lib/
                ├──cmsis-dsp/
                └──cmsis-nn/
           └── fs/
                ├── fatfs/
                └── littlefs/  
     └── zephyr/
           ├── arch/
           ├── boards/
           ├── cmake/
           ├── drivers/
           ├── include/
           ├── kernel/
           ├── samples/
           ├── scripts/
           ├── soc/
           ├── subsys/
           ├── tests/
           └── west.yml
     ├── tools/     
     └── apps/  
          ├── project_1
          └── project_2
     └── build/
          ├── project_1
          └── project_2            

Zephyr Board Directory

• Kconfig.<board_name>: Defines board- and SoC-related Kconfig settings
• <board_name>_defconfig: Defines default Kconfig options for the board
• <board_name>.dts: Describes the board’s hardware using Devicetree
• <board_name>.yaml: Defines board metadata and capabilities for automated testing
• board.cmake: Configures runners for flashing and debugging
• board.yml: Defines board identity, SoC, revisions, and variants

└── zephyr/
      └── boards/
            └── vendor/
                  └── <board_name>/
                          ├── Kconfig.<board_name>
                          ├── <board_name>_defconfig
                          ├── <board_name>.dts
                          ├── <board_name>.yaml
                          ├── board.cmake
                          └── board.yml

└── zephyr/
      └── boards/
            └── vendor/
                  └── <board_name>/
                          ├── Kconfig.<board_name>
                          ├── <board_name>_defconfig
                          ├── <board_name>.dts
                          ├── <board_name>.yaml
                          ├── board.cmake
                          └── board.yml

Zephyr Application Directory

• CMakeLists.txt: Connects the project to Zephyr’s build system
• Kconfig: Defines application options, their types, defaults, and dependencies
• prj.conf: Configures application, Zephyr, and module features by setting option values
• extra.conf: Optional Kconfig configuration fragment used to add or override settings in prj.conf for a particular build
• <board_name>.conf: Board-specific Kconfig settings
• <board_name>.overlay: Board-specific Devicetree hardware changes

└── apps/  
      └── project_1
             ├── CMakeLists.txt
             ├── Kconfig
             ├── prj.conf
             ├── extra_1.conf
             ├── extra_2.conf
             ├── app.overlay
             └── boards/
                  ├── <board_name_1>.conf 
                  ├── <board_name_1>.overlay
                  ├── <board_name_2>.conf
                  └── <board_name_2>.overlay
             └── src/
                  └── main.c

└── apps/  
      └── project_1
             ├── CMakeLists.txt
             ├── Kconfig
             ├── prj.conf
             ├── extra_1.conf
             ├── extra_2.conf
             ├── app.overlay
             └── boards/
                  ├── <board_name_1>.conf 
                  ├── <board_name_1>.overlay
                  ├── <board_name_2>.conf
                  └── <board_name_2>.overlay
             └── src/
                  └── main.c

Zephyr Build Directory

A Zephyr application goes through multiple build stages before producing the final executable. A pristine build removes the existing build directory before starting a new build. This forces CMake, Kconfig, and Devicetree to run from scratch instead of reusing cached results.

• .conf: The final resolved Kconfig configuration for the current build
• autoconf.h: The C header generated from .config so the selected Kconfig options can be used by C/C++ source code.

└── build/
      └── project_1
              └── zephyr/
                    ├── zephyr.elf
                    ├── zephyr.hex
                    ├── zephyr.bin
                    ├── zephyr.map
                    ├── zephyr.dts (merged Devicetree output)
                    ├── .config
                    └── include/generated/zephyr/
                            ├── autoconf.h (Kconfig output)
                            └── devicetree_generated.h (Devicetree macros)

└── build/
      └── project_1
              └── zephyr/
                    ├── zephyr.elf
                    ├── zephyr.hex
                    ├── zephyr.bin
                    ├── zephyr.map
                    ├── zephyr.dts (merged Devicetree output)
                    ├── .config
                    └── include/generated/zephyr/
                            ├── autoconf.h (Kconfig output)
                            └── devicetree_generated.h (Devicetree macros)

Reference

[1] Zephyr Project Documentation
[2] Zephyr API Reference
[3] Samples and Demos
[4] Supported Boards and Shields
[5] Zephyr Workspace
[6] Zephyr Application Development
[7] Zephyr Build and Configuration Systems
[8] Zephyr Build System (CMake)
[9] West Manifests

FreeRTOS Heap Implementation Compared

Memory Fragmentation Process

heap_1.c

heap_1.c is the simplest FreeRTOS heap implementation and provides dynamic memory allocation through pvPortMalloc(). It manages a statically allocated heap defined by configTOTAL_HEAP_SIZE and allocates memory sequentially from the beginning of this heap. Once memory is allocated, it cannot be returned to the heap because heap_1.c does not support vPortFree(). This makes the implementation very small, fast, and deterministic, with no risk of heap fragmentation. It is most suitable for embedded applications in which all dynamic memory is allocated during system initialization and never released, such as systems that create all tasks, queues, semaphores, and other RTOS objects before starting normal operation.

heap_2.c

heap_2.c provides dynamic memory allocation through pvPortMalloc() and supports releasing memory with vPortFree(). It manages a statically allocated heap and reuses previously freed blocks when possible. However, adjacent free blocks are not combined, so repeated allocations and deallocations of different sizes can cause memory fragmentation over time. It is mainly suitable for applications that allocate and free blocks of the same or similar sizes, although heap_4.c is generally preferred for most applications that require memory to be freed.

heap_3.c

heap_3.c implements the FreeRTOS memory allocation interface by wrapping the standard C library functions malloc() and free(). Unlike the other FreeRTOS heap implementations, it does not use the memory region defined by configTOTAL_HEAP_SIZE; instead, memory management is handled by the C runtime library. This implementation is useful when an application already relies on the standard library heap, but its determinism, thread safety, fragmentation behavior, and memory usage depend on the specific C library and system configuration.

heap_4.c

heap_4.c is a commonly used FreeRTOS heap implementation that supports both dynamic allocation with pvPortMalloc() and deallocation with vPortFree(). It manages a statically allocated heap and automatically combines adjacent free memory blocks, which significantly reduces memory fragmentation compared with heap_2.c. It provides a good balance between simplicity, efficiency, and flexibility, making it well suited for applications that dynamically create and delete tasks, queues, semaphores, and other RTOS objects during runtime.

// ---------------------- Example ----------------------

uint8_t *buffer = NULL;
buffer = pvPortMalloc(32);
printf("Allocated memory at address: %p\r\n", (void *)buffer);

printf("Freeing memory at address: %p\r\n", (void *)buffer);
vPortFree(buffer);
buffer = NULL;

size_t freeMem;
freeMem = xPortGetFreeHeapSize();
printf("Free heap memory: %u bytes\r\n", (uint16_t)freeMem);

// ---------------------- Example ----------------------

uint8_t *buffer = NULL;
buffer = pvPortMalloc(32);
printf("Allocated memory at address: %p\r\n", (void *)buffer);

printf("Freeing memory at address: %p\r\n", (void *)buffer);
vPortFree(buffer);
buffer = NULL;

size_t freeMem;
freeMem = xPortGetFreeHeapSize();
printf("Free heap memory: %u bytes\r\n", (uint16_t)freeMem);

heap_5.c

heap_5.c provides the same allocation and deallocation behavior as heap_4.c, including the ability to merge adjacent free blocks, but it can manage multiple separate memory regions instead of a single contiguous heap. The available regions are defined by the application using vPortDefineHeapRegions(), allowing FreeRTOS to use memory located in different RAM banks or address ranges. It is particularly useful on microcontrollers with multiple RAM regions, such as internal SRAM, CCM RAM, or external memory, where the application needs to combine several non-contiguous areas into a single FreeRTOS heap.

typedef struct HeapRegion {
    uint8_t *pucStartAddress;  // Start address of the memory block
    size_t xSizeInBytes;       // Size of the memory region
} HeapRegion_t;

HeapRegion_t xHeapRegions[] = {
    { ( uint8_t * ) 0X10000000UL, 0x10000 },   // CCM memory, start address 0X10000000, size 64 KB
    { ( uint8_t * ) 0X20000000UL, 0x20000 },   // Internal SRAM, start address 0X20000000, size 128 KB
    { ( uint8_t * ) 0X68000000UL, 0x100000 },  // External SRAM, start address 0X68000000, size 1 MB
    { NULL, 0 }                                // End of the array
};

// Initialize the heap memory
vPortDefineHeapRegions((const HeapRegion_t *)xHeapRegions);

typedef struct HeapRegion {
    uint8_t *pucStartAddress;  // Start address of the memory block
    size_t xSizeInBytes;       // Size of the memory region
} HeapRegion_t;

HeapRegion_t xHeapRegions[] = {
    { ( uint8_t * ) 0X10000000UL, 0x10000 },   // CCM memory, start address 0X10000000, size 64 KB
    { ( uint8_t * ) 0X20000000UL, 0x20000 },   // Internal SRAM, start address 0X20000000, size 128 KB
    { ( uint8_t * ) 0X68000000UL, 0x100000 },  // External SRAM, start address 0X68000000, size 1 MB
    { NULL, 0 }                                // End of the array
};

// Initialize the heap memory
vPortDefineHeapRegions((const HeapRegion_t *)xHeapRegions);