STM32CubeIDE 프로젝트에 FreeRTOS 커널을 수동 추가하는 방법

이 글에서는 STM32CubeIDE로 생성한 STM32F407 Discovery 기본 프로젝트에 FreeRTOS 커널을 수동으로 포함하는 과정을 단계별로 설명합니다.
CubeMX의 자동 생성 기능 대신 “수동 추가” 방식을 익히면, 다른 MCU나 IDE에서도 바로 응용할 수 있으므로 학습 가치가 높습니다.

---

목차

1. 작업 폴더 구조 준비
2. STM32CubeIDE에서 STM32F407 프로젝트 생성
3. FreeRTOS 커널 다운로드 및 폴더 구조 개요
4. 프로젝트에 FreeRTOS 소스코드 수동 복사
5. 불필요한 파일 정리 (포팅 코드, 메모리 관리)
6. Build 시도 및 오류 원인 확인
7. 다음 글 미리보기: Include 경로 설정 및 FreeRTOSConfig.h 작성

---

1. 작업 폴더 구조 준비

1. 대용량 디스크(예: D:)에 Workspace 폴더를 생성
2. 그 안에 RTOS_workspace와 Software_and_Toolchain 두 개의 하위 폴더를 만든다.
   • RTOS_workspace
     • 이곳을 STM32CubeIDE의 워크스페이스로 지정
     • FreeRTOS 관련 모든 STM32CubeIDE 프로젝트를 저장
   • Software_and_Toolchain
     • GCC 같은 컴파일러, FreeRTOS ZIP 파일 등 외부 의존물을 보관

팁: STM32CubeIDE를 실행하면 워크스페이스 경로로 D:\Workspace\RTOS_workspace를 지정하세요.

---

2. STM32CubeIDE에서 STM32F407 프로젝트 생성

1. STM32CubeIDE 실행
2. File → New → STM32 Project 선택
3. Board Selector 탭에서 32F4DISCOVERY 검색 후 선택 (STM32F407 Discovery 보드)
4. 프로젝트 이름을 예: FreeRTOS_Project로 지정
5. Project Type: STM32Cube-based Project 선택
   • “Initialize all peripherals with default mode?” → No
   • “Open Device Configuration Tool?” → Yes (CubeMX 설정 화면이 뜨면 닫아도 무방)
6. Finish 클릭 → 기본 HAL + CMSIS만 포함된 프로젝트 생성 완료

현재 프로젝트에는 FreeRTOS가 전혀 없으며, “HAL + CMSIS”만 들어 있습니다.

---

3. FreeRTOS 커널 다운로드 및 폴더 구조 개요

3.1. FreeRTOS 커널 ZIP 파일 받기

1. 브라우저에서 freertos.org 접속
2. 상단 메뉴 “Download” → “FreeRTOS Kernel” 클릭
3. 예: FreeRTOSv202012.00.zip 파일 다운로드 →
   D:\Workspace\Software_and_Toolchain\FreeRTOSv202012.00.zip에 저장
4. ZIP 압축 해제 → D:\Workspace\Software_and_Toolchain\FreeRTOSv202012.00\FreeRTOS\ 폴더 확보

3.2. FreeRTOS 폴더 구조 요약

FreeRTOSv202012.00/
└─ FreeRTOS/                    ← 커널 소스 최상위 폴더
   ├─ include/                  ← FreeRTOS 헤더 (FreeRTOS.h, task.h 등)
   ├─ source/                   ← 커널 코드 (.c 파일들)
   └─ portable/                 ← 포팅 코드 (컴파일러·아키텍처별)
       ├─ GCC/                  ← GCC용 포팅 코드
       │   └─ ARM_CM4F/         ← STM32F407(Cortex-M4F)용 포팅
       └─ MemMang/              ← 메모리 관리( heap_1.c ~ heap_5.c )

• include/: 커널 헤더
• source/: 커널 소스 (.c)
• portable/:
  • 아키텍처 및 컴파일러별 포팅 코드
  • GCC/ARM_CM4F/: STM32F407을 위한 포팅 코드 (실행 컨텍스트 전환, 스택 초기화 등)
  • MemMang/: FreeRTOS 고유의 힙 관리 방식 제공 (heap_1~heap_5)

---

4. 프로젝트에 FreeRTOS 소스코드 수동 복사

4.1. IDE에서 ThirdParty 폴더 생성

1. 프로젝트 이름 위에서 우클릭 → New → Folder
2. 폴더 이름: ThirdParty → Finish

4.2. 파일 탐색기로 FreeRTOS 소스 복사

1. 파일 탐색기 열기 → D:\Workspace\Software_and_Toolchain\FreeRTOSv202012.00\FreeRTOS\로 이동
2. include/, source/, license/ 폴더 전체를 복사
3. STM32CubeIDE 프로젝트 경로에 붙여넣기
4. D:\Workspace\RTOS_workspace\FreeRTOS_Project\ThirdParty\FreeRTOS\

4.3. portable 폴더 복사 및 불필요 파일 삭제

1. 다시 FreeRTOSv202012.00\FreeRTOS\portable\ 폴더 전체 복사 → 프로젝트 내 ThirdParty\FreeRTOS\portable\에 붙여넣기
2. portable\ 폴더 안에서 다음 세 개 제외하고 나머지 모두 삭제:
   • GCC/
   • MemMang/
   • README.md
3. portable\GCC\로 들어가서 STM32F407(Cortex-M4F)에 해당하는 ARM_CM4F/ 폴더만 남기고 다른 아키텍처 폴더(ARM_CM0, ARM_CM0plus 등) 전부 삭제
4. portable\MemMang\로 들어가서, FreeRTOS가 권장하는 힙 관리 방식인 heap_4.c만 남기고 나머지 heap_1.c, heap_2.c, heap_3.c, heap_5.c 삭제

이 작업 이유

• 우리는 GCC + STM32F407(Cortex-M4F) 조합만 사용할 예정
• 다른 컴파일러·아키텍처 코드는 쓰이지 않으므로 제거
• 힙 관리 방식은 FreeRTOS 가이드라인 heap_4.c만 사용

---

5. 불필요한 파일 정리 및 빌드 시도

5.1. sysmem.c 제외하기

Drivers/CMSIS/Src/sysmem.c는 표준 라이브러리의 malloc/new 호출 등용으로 Linux/OS 환경용 파일입니다.
FreeRTOS가 자체적으로 힙 관리를 제공하므로 우리 프로젝트에선 필요 없음 → exclude 처리

1. STM32CubeIDE Project Explorer에서 Drivers → CMSIS → Src → sysmem.c 우클릭
2. Properties → C/C++ Build 선택
3. “Exclude resource from build” 체크 → 적용

5.2. FreeRTOS 파일 빌드 포함 설정

1. Project Explorer에서 ThirdParty/FreeRTOS 폴더 우클릭
2. Properties → C/C++ Build
3. “Exclude resource from build”가 체크 해제되어 있는지 확인 (빌드 대상 포함)

5.3. 첫 빌드 시도 및 오류 확인

• Project → Build Project 실행
• 뜨는 오류:이는 FreeRTOS의 헤더 위치가 아직 Include Path에 등록되지 않았기 때문
• fatal error: FreeRTOS.h: No such file or directory
• 이 단계까지 완료했다면, 다음 글에서 Include 경로 설정과 FreeRTOSConfig.h 작성 과정을 상세히 다룹니다.

---

6. 마무리 및 다음 글 예고

지금까지 FreeRTOS 커널 소스 전체를 STM32CubeIDE 프로젝트에 복사하고 불필요한 포팅·메모리 관리 파일을 제거해 보았습니다.
하지만 빌드 오류를 해결하려면 IDE에 “FreeRTOS 헤더 경로”와 “포팅 코드 경로”를 알려줘야 합니다.

다음 글 내용

1. Include Path 설정
   • Project → Properties → C/C++ Build → Settings → MCU GCC Compiler → Includes

   • …\RTOS_workspace\FreeRTOS_Project\ThirdParty\FreeRTOS\include  
     …\RTOS_workspace\FreeRTOS_Project\ThirdParty\FreeRTOS\portable\GCC\ARM_CM4F  
     

2. FreeRTOSConfig.h 파일 작성
   • CPU 클럭 주파수, 태스크 우선순위, 힙 크기 등 필수 설정
3. 헬로 월드 태스크 구현
   • vTaskCreate()로 태스크 생성 → 디버거 또는 UART로 “Hello World” 출력
   • vTaskStartScheduler() 호출 후 스케줄러 구동 확인

위 단계를 차근차근 따라가면 **“FreeRTOS 헬로 월드 예제”**가 STM32F407 Discovery 보드에서 정상 실행됩니다.
다음 글에서 이어서 설명하겠습니다.

---

이 글을 참고하여 프로젝트 구조를 미리 준비해 보세요.
다음 글에서는 실제로 FreeRTOS가 동작하도록 설정하고, 첫번째 태스크를 구현합니다.