zephyr-foundations

name	zephyr-foundations
description	Foundational skills for Zephyr RTOS development. Covers essential Embedded C patterns (BIT, CONTAINER_OF), real-time concurrency primitives (mutexes, semaphores, spinlocks), hardware literacy (datasheet-to-DTS mapping), and defensive programming. Trigger when writing core application logic, drivers, or troubleshooting foundational behavior.

Zephyr Foundations

Mastering the bedrock of Zephyr is essential for writing efficient, robust, and idiomatic code.

Core Workflows

1. Idiomatic C Patterns

Zephyr uses specific macros to manage memory and hardware-software mapping.

• Reference: zephyr_macros.md
• Key Tools: CONTAINER_OF, BIT(), GENMASK(), ARRAY_SIZE.

2. Real-Time Concurrency

Safe multi-threading and interrupt handling are critical for stability.

• Reference: concurrency.md
• Key Tools: k_mutex, k_sem, k_spinlock, atomic_t, ISR safety rules.

3. Hardware Literacy (Devicetree)

Understanding how code interacts with the hardware description.

• Reference: devicetree_basics.md
• Key Tools: Nodes, properties, phandles, overlays, and advanced deletion.

4. Robust Error Handling

Preventing crashes through defensive programming.

• Reference: error_handling.md
• Key Tools: errno.h, BUILD_ASSERT, validation patterns, return code checking.

Quick Start (Defensive Pattern)

int sensor_read_checked(const struct device *dev)
{
  if (dev == NULL || !device_is_ready(dev)) {
    return -ENODEV;
  }

  return 0;
}

Validation Checklist

• Shared bit-field logic uses Zephyr macros (BIT, GENMASK) instead of raw literals.
• Thread-shared state is protected with mutex/spinlock/atomic primitives.
• Error paths return standard negative errno codes.
• Defensive guards exist for null pointers, bounds, and device readiness checks.

Automation Tools

• errno_return_check.py: Detect likely non-negative errno return statements in C/C++ code.

Examples & Templates

• template_driver.c: A complete skeleton showing how to combine DT macros, mutexes, and config-data separation.

Resources

• References:
  • zephyr_macros.md: Essential macros (BIT, CONTAINER_OF, etc.).
  • concurrency.md: Mutexes, Semaphores, Spinlocks, and ISR safety.
  • devicetree_basics.md: Devicetree syntax and overlay patterns.
  • error_handling.md: Error codes and defensive programming.
• Scripts:
  • errno_return_check.py: Return-code sign checker.
• Assets:
  • foundation_examples/: Working code templates for drivers and logic.