Wiznet makers

This is an official guide document summarizing the changes developers need to modify or pay attention to when upgrading (migrating) the Real-Time Operating System (RTOS) Zephyr from v4.3.0 to v4.4.0.

1. Key Summary of the Zephyr v4.4.0 Migration Guide

Changes in Build System and Environment

The minimum required environment has been raised to Zephyr SDK 1.0.0 and Python 3.12.

The default C language standard has been changed to C17 (ISO/IEC 9899:2018). Separate configuration is required if using an older toolchain.

Changes in Kernel Memory Management

The previously supported optional kernel memory pinning model (__pinned_* attributes and related Kconfig) has been completely removed for safety reasons.

Kernel images now reside strictly in physical memory. Apps that relied on the previous method of dynamically loading and unloading code into memory (Demand Paging) will require code modifications (such as changing to non-pinned macros).

Stricter Rules for Boards and Device Trees

Flash file specification flags in the OpenOCD Runner have been standardized (e.g., --file-type=hex), and older flags will now trigger a warning.

Kconfig option names for various SoCs, including NXP, Nordic, and Sifive, have been extensively reorganized (deprecated/replaced).

Forcing default values ​​for attributes such as status and #address-cells in the device tree will now result in a build error.

Changes to Driver and Subsystem Structure (Device Drivers & Subsystems)

Kconfig and APIs used by numerous sub-drivers, including Ethernet, Bluetooth, Wi-Fi, and ADC, have been standardized or renamed.

2. The Meaning of 'W5500' in This Document

The W5500 is a well-known hardware TCP/IP Ethernet controller chip manufactured by the Korean company WIZnet. (Device tree compatible names within this document: wiznet,w5500)

The W5500 is mentioned in the [Device Drivers and Devicetree -> Ethernet] section of this migration document, and the significance is as follows:

Standardization of MAC Address Configuration API: Starting with Zephyr version 4.4.0, the MAC address configuration method for Ethernet drivers has been standardized to use a common structure called net_eth_mac_config.

W5500 Driver Improvements (GitHub PR #100919): This means that this new standard MAC address configuration feature has been newly introduced to the W5500 driver (included as one of the drivers to which it has been applied).

In conclusion, this implies that when using the W5500 Ethernet chip based on Zephyr 4.4.0, the code for configuring and initializing the MAC address has been improved to meet Zephyr's latest public network API standards, so please refer to this section during migration.

=================================

실시간 운영체제(RTOS)인 Zephyr v4.3.0에서 v4.4.0으로 버전을 업그레이드(마이그레이션)할 때 개발자가 수정하거나 주의해야 할 변경 사항을 정리한 공식 가이드 문서입니다.

2026년 5월 15일.

1. Zephyr v4.4.0 마이그레이션 가이드 주요 요약

빌드 시스템 및 환경 변화 (Build System)

최소 요구 환경이 Zephyr SDK 1.0.0 및 Python 3.12로 상향되었습니다.

C 언어 표준의 기본값이 C17 (ISO/IEC 9899:2018)로 변경되었습니다. 구형 툴체인을 쓴다면 별도 설정이 필요합니다.

커널 메모리 관리 변화 (Kernel)

기존에 지원되던 선택적 커널 메모리 고정 모델(__pinned_* 속성 및 관련 Kconfig)이 안전상의 이유로 완전히 제거되었습니다.

이제 커널 이미지는 무조건 물리 메모리에 상주하며, 코드를 메모리에 동적으로 올리고 내리던(Demand paging) 기존 방식에 의존하던 앱들은 코드 수정(비고정 매크로로 변경 등)이 필요합니다.

보드(Boards) 및 디바이스 트리(Devicetree) 규칙 엄격화

OpenOCD 러너(Runner)의 플래시 파일 지정 플래그가 표준화(--file-type=hex 등)되며 구형 플래그는 경고를 띄웁니다.

NXP, Nordic, Sifive 등 다양한 SoC의 Kconfig 옵션 이름이 대거 개편(Deprecated/Replaced)되었습니다.

디바이스 트리에서 status, #address-cells 등의 속성에 기본값(Default)을 강제로 지정하면 이제 빌드 에러가 발생합니다.

드라이버 및 서브시스템 구조 변경 (Device Drivers & Subsystems)

이더넷, 블루투스, Wi-Fi, ADC 등 수많은 하위 드라이버에서 사용되던 Kconfig와 API들이 표준화되거나 이름이 변경되었습니다.

2. 이 문서에서 'W5500'이 가지는 의미

이 글에서 W5500은 단순히 “WIZnet 제품명이 언급됐다”는 수준이 아니라, Zephyr mainline Ethernet driver ecosystem 안에서 W5500 driver가 공식적으로 migration 대상에 포함되었다는 의미입니다.

이 마이그레이션 문서의 [Device Drivers and Devicetree -> Ethernet] 섹션에서 W5500이 언급되는데, 그 의미는 다음과 같습니다.

MAC 주소 설정 API의 표준화 적용: Zephyr 4.4.0 버전부터 이더넷 드라이버들의 MAC 주소 설정 방식이 net_eth_mac_config라는 공통 구조체를 사용하는 방식으로 표준화되었습니다.

W5500 드라이버 개선 (GitHub PR #100919): 이러한 새로운 표준 MAC 주소 설정 기능이 W5500 드라이버에도 새롭게 도입(도입 적용된 드라이버 목록 중 하나로 포함)되었다는 뜻입니다.

결론적으로, Zephyr 4.4.0 기반으로 W5500 이더넷 칩을 사용할 때, MAC 주소를 구성하고 초기화하는 코드가 Zephyr의 최신 공용 네트워크 API 기준에 맞게 개선되었으니 마이그레이션 시 이 부분을 참고하라는 의미를 담고 있습니다.

[같은 도메인 과거 UCC 글들]

[Q&A]

[Q] 

위와 같이 zephyr 버전 변환 마이그레이션을 하는데, WIZnet은 어떻게 대응해야 하는가?

[A]

WIZnet 프로젝트의 Zephyr v4.4.0 마이그레이션 대응 가이드

1. 빌드 환경 및 C 표준 업그레이드

컴파일러 표준 대응: Zephyr v4.4.0부터는 최소 요구 C 표준 버전이 C17로 공식 상향되었습니다. WIZnet 드라이버를 제어하는 자체 애플리케이션 코드나 외부 라이브러리가 C17 표준 빌드 환경에서 컴파일 에러를 일으키지 않는지 확인해야 합니다.

호스트 환경 업데이트: 최소 요구 Zephyr SDK는 1.0.0 버전, 호스트 Python 버전은 3.12 이상으로 환경을 먼저 업데이트한 후 빌드를 진행해야 합니다.

2. 이더넷 드라이버 표준 MAC 설정 API 적용

런타임 MAC 설정 구조 변경: v4.4.0 네트워크 서브시스템 개편에 따라 이더넷 드라이버들의 MAC 주소 설정 구조가 표준화되었습니다. W5500 드라이버 역시 새로운 표준 런타임 MAC 설정 아키텍처에 맞추어 리팩토링이 적용되었습니다.

대응 방법: 기존에 애플리케이션 단에서 W5500의 고유 MAC 주소를 초기화하거나 수동으로 변경하기 위해 사용했던 구형 레거시 API가 있다면, 개편된 공용 네트워크 인터페이스 구조체 및 드라이버 API 규격에 맞게 소스 코드를 수정해야 합니다.

3. 커널 메모리 고정 매크로(__pinned_*) 전면 제거

고정 섹션 삭제: 이더넷 통신(W5500)은 실시간 인터럽트와 패킷 처리가 중요하기 때문에, 이전 버전에서는 관련 버퍼나 ISR 함수들을 인터럽트 지연을 줄이기 위해 메모리에 강제로 상주시키는 __pinned_func 또는 __pinned_data 속성을 종종 사용했습니다.

대응 방법: v4.4.0부터는 이 고정 섹션 모델이 완전히 제거되고 커널 이미지가 항상 물리 메모리에 상주하도록 변경되었습니다. 따라서 WIZnet 소스 코드나 보드 파일 내에 남아있는 __pinned_* 형태의 매크로 속성 및 관련 Kconfig 설정(CONFIG_LINKER_USE_PINNED_SECTION 등)은 모두 삭제해야 빌드 오류를 막을 수 있습니다.

4. 디바이스트리(Devicetree) 파티션 맵 수정

코드 파티션 맵 변경: 펌웨어 저장 공간이나 부트로더 영역을 정의할 때 사용하던 zephyr,code-partitionChosen 노드가 이제 구형 fixed-partitions 방식 대신 새로운 zephyr,mapped-partition 구조를 사용하도록 권장됩니다.

대응 방법: W5500-EVB-Pico2 등 WIZnet 계열 보드 파일을 커스텀하여 사용 중이었다면, .dts 또는 .overlay 파일에서 플래시 메모리 파티션을 정의할 때 이 새로운 매핑 규칙을 적용하여 링커 파일이 NVM 오프셋과 크기를 자동으로 계산할 수 있도록 구조를 다듬어야 합니다.