# ICFramework

**Repository Path**: yys_cn_ccs/icframework

## Basic Information

- **Project Name**: ICFramework
- **Description**: ICFrameWork
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IC-Framework (Intent Clarity Framework)

> Intent Clarity is greater than everything.

## 1. Project Goal

IC-Framework is a layered embedded firmware framework. It is designed to:

1. Decouple business logic from chip/board/OS differences.
2. Reuse upper layers across STM32 (FreeRTOS) and Win32 host simulation.
3. Keep portability predictable through clear adaptation boundaries.

## 2. Layered Architecture

| Layer | Directory | Responsibility | Constraint |
| --- | --- | --- | --- |
| Application | `app/` | Business workflow and app entry | Do not call HAL directly |
| Contracts | `contracts/` | Stable board/resource naming contracts | No runtime logic |
| Components | `components/` | Reusable capabilities (`fs/mem/storage/transfer`) | No board/SoC binding code |
| Driver Framework | `driver/` | Unified driver/device/bus abstraction | Avoid chip-specific implementation |
| OS Abstraction | `osal/` | Thread/lock/queue/time abstraction | No business logic |
| Platform Adaptation | `platform/` | Board, port-family, SoC realization | May use HAL/CMSIS/host APIs |
| Utilities | `utils/` | Logging, containers, common helpers | Prefer platform-agnostic |
| Tests | `tests/` | Unit/integration/verification | Verify through abstraction interfaces |

Dependency direction:

`app -> contracts/components/driver -> osal/utils`

`platform -> contracts + generic layers`

## 3. Platform Layout (Current)

```text
ICFramework/platform/
|- bootstrap/
|  |- inc/
|  `- src/
|- runtime/
|  |- inc/
|  `- src/
|- boards/
|  |- wildfire/wf_stm32f429igt6/{board_init.c,providers/}
|  `- host/win32_host/{board_init.c,providers/}
|- ports/
|  |- os_freertos/
|  |  |- stm32/{osal,hal,fs,memory,bootstrap}
|  |  `- gd32/{osal,hal,fs,memory,bootstrap}
|  `- os_win32/
|     `- win32/{osal,hal,fs,memory,bootstrap}
`- soc/
   `- st/stm32f4xx/

ICFramework/contracts/
`- board/
```

Placement rules:

1. `boards/`: board-instance-specific resources (pinmux/clkctrl/peripheral instances/board-local SDRAM).
2. `contracts/board/`: stable board naming contracts visible to app/test/driver.
3. `ports/<os_group>/<family>/`: OS-runtime constrained port adaptation (OSAL, HAL providers, diskio, memory adapter, bootstrap).
4. `soc/<vendor>/<soc>/`: true SoC shared capabilities (not board-local device instances).

## 4. Why Win32 Is Not a SoC

Win32 in this repository is a host simulation target, not a silicon SoC.

1. Keep Win32 under `ports/os_win32/win32`, and keep MCU ports under `ports/os_freertos/*`.
2. Keep `soc/` dedicated to real SoC vendor/chip capability sharing.
3. Board file `config/boards/win32_host/board.cmake` sets SoC fields empty intentionally.

## 5. FatFs Boundary

FatFs core remains in `components/fs/fatfs`.

Disk I/O media adapters are platform-specific and stay in ports:

1. STM32: `platform/ports/os_freertos/stm32/fs/fatfs_diskio_spi_flash.c`
2. Win32: `platform/ports/os_win32/win32/fs/fatfs_diskio_ram.c`

## 6. Build and Verification (Workspace Root)

Run these commands from the workspace root (`ICFrameworks/`), not from this submodule folder.

### 6.1 STM32 (FreeRTOS)

```bash
cmake --preset Debug
cmake --build --preset Debug
```

Common targets:

```bash
cmake --build --preset Flash-Debug
cmake --build --preset Verify-RTT-Debug
cmake --build --preset Flash-And-Verify-RTT-Debug
```

### 6.2 Win32

```bash
cmake --preset Win32-Debug
cmake --build --preset Win32-Debug
```

## 7. Development Checklist

1. Confirm the target layer before coding.
2. Implement in the owned layer only.
3. Add minimal verification.
4. Update related CMake and documentation with boundary changes.

---

**Author**: xiongzhaoquan
**Last Updated**: 2026-04-11