# PROJECT KNOWLEDGE BASE

**Generated:** 2026-06-15
**Version:** CUni360S-Z DEMO V3.4 (SDK V3.6)
**IDE:** CCore Eclipse CDT (C*Core C0 architecture)

## OVERVIEW

Firmware demo for the **C*Core CUni360S-Z** secure MCU — a Chinese-designed RISC SoC targeting financial/identification terminals (POS, card readers). Demonstrates all on-chip peripherals and hardware crypto engines (SM1/2/3/4, DES/3DES, AES, RSA, SHA, TRNG) plus smart card (ISO 7816), USB device classes, and certificate (X.509/PKCS7) handling.

## STRUCTURE

```
CUni360S-Z_Demo/
├── .project/.cproject    # Eclipse CDT project (name: CUni360S-Z_Demo_V1)
├── linkmap               # Linker script (NOT .ld — plain text, GCC-style)
├── gdbinit               # GDB remote debug config (JTAG localhost:3333)
├── include/              # Core headers: types, memmap, interrupts, boot
├── src/
│   ├── main.c            # Entry point — init sequence + demo dispatch
│   ├── ccore/            # C*Core startup: vectors, interrupt table
│   ├── drv/              # Peripheral drivers + register definitions
│   │   └── inc/          # All driver headers + xxx_reg.h register maps
│   ├── app/              # Application-layer protocol implementations
│   │   ├── apdu/         # APDU command dispatcher (smart card)
│   │   ├── cert/         # SM2 cert generation, X.509, PKCS7, Base64
│   │   ├── icc/          # ICC/ISO 7816 T0/T1 + EMV L1
│   │   ├── mcc/          # Magnetic card reader (MCC ADC)
│   │   ├── norflash/     # External NOR flash via SPI3
│   │   ├── rtc/          # RTC application
│   │   └── usb/          # USB device classes (CCID/CDC/HID/UMS)
│   ├── demo/             # Demo function per peripheral/feature
│   └── common/           # Debug printf, assert
├── build_config/         # Build config (project_type:0)
├── debug_eflash/         # TCL scripts for flash erase/program
├── Debug/                # Build output (.elf, .bin, .map, .o, .d)
└── .metadata/            # Eclipse workspace state — IGNORE
```

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| Add a new peripheral demo | `src/demo/` + toggle in `test_demo.h` | Pattern: `xxx_demo.c/.h` |
| Use crypto (AES/DES/SM4/SM2/RSA) | `src/drv/inc/alg_drv.h` | Hardware engine APIs |
| Smart card / ISO 7816 | `src/app/icc/` | T0/T1, EMV L1 |
| Certificate operations | `src/app/cert/` | X.509, PKCS7, SM2 certs |
| USB class implementation | `src/app/usb/` | Enable in `usb_config.h` |
| Memory map / register base | `include/memmap.h` | All peripheral base addresses |
| Type definitions | `include/type.h` | UINT8/16/32, bool, FlagStatus |
| Boot / clock / power | `src/drv/inc/cpm_drv.h` | SysClk, module clocks, card LDO |
| Linker layout | `linkmap` | eFlash 512K@0x400000, RAM 64K@0x800000 |
| Debug via GDB | `gdbinit` | `target remote localhost:3333` |

## HARDWARE SPEC

| Resource | Detail |
|----------|--------|
| **Core** | C*Core C0 (NOT ARM) — little endian |
| **Clock** | OSC 120MHz, default sys = 60MHz (div 2) |
| **eFlash** | 0x00400000, 512KB |
| **RAM** | 0x00800000, 64KB |
| **Stack** | Top at 0x80fffc, heap ends 0x2000 below |
| **Crypto HW** | SM1(0x63f1c000), SM2, SM4(0x00de0000), AES(0x00cf0000), DES(0x00c90000), SHA(0x63f64000), TRNG(0x63f40000) |
| **Peripherals** | SPI×3, SCI/UART×2, I2C, USB, ADC, PWM, PIT, PIT32, DMA, EDMA, CRC×2, RTC, WDT, EPORT, PCI, USI×2 |
| **Smart card I/F** | USI2/USI3 (ISO 7816), voltage: 1.8V/3V/3.3V/5V selectable |

## CONVENTIONS

- **Include guards**: `#ifndef NAME_H_` / `#define NAME_H_` (never `#pragma once`)
- **Types**: Use `UINT8/UINT16/UINT32/INT8/INT16/INT32` from `type.h` — NOT `uint8_t`
- **Function naming**: `MODULE_ActionCase()` — e.g., `UART_Init()`, `CPM_SysClkSelect()`, `AES_EnDecrypt()`
- **Register access**: `#define PERIPH ((PERIPH_TypeDef *)(BASE_ADDR))` then `PERIPH->REG |= bit`
- **File naming**: `module_drv.c` / `module_reg.h` (driver+register split)
- **Header style**: `// ~~~~` banner or `/* Author */` block
- **Power macros**: `CARD0_POWER_ON`, `USB_POWER_ON` etc. — `do{}while(0)` wrappers
- **Validation**: `assert_param(expr)` macro, `IS_xxx_RANGE()` guard macros
- **printf**: Custom `my_printf` (aliased via `#define printf my_printf`) — costs ~2KB RAM, controlled by `DEBUG_LOG`
- **Comments**: GB2312/GBK encoded Chinese — will appear garbled in UTF-8 editors

## ANTI-PATTERNS (THIS PROJECT)

- **PWM_DEMO conflicts**: Cannot run PWM demo simultaneously with others — shared pins with NorFlash. Comment in `main.c`: "两个不能同时打开"
- **BCTC_TEST_DEMO disables cache**: EMV L1 timing requirements — `CACHE_Init(cacheOff, ...)` is skipped
- **EDMAC clock discipline**: AES/DES/SM4/SHA/SM2 operations require EDMAC clock ON before, OFF after — functions manage this internally but caller must not nest
- **TRNG must init first**: Call `Init_Trng()` before any SM2 key generation (internally uses TRNG)
- **Module clocks**: Must call `ModuleClk_On(MODULE_CLK_xxx)` before using any peripheral; `ModuleClk_Off()` to save power
- **Boot return**: `reback_boot()` checks I2C_SDA pin — if LOW, calls `EnBootMode(0)` and infinite loops (returns to bootloader)
- **USB class selection**: Only enable ONE USB class at a time in `usb_config.h` (currently CCID=1, others=0)
- **EFLASH clock**: Must call `EFLASH_Init(g_sys_clk)` at startup with current system clock frequency

## UNIQUE STYLES

- **Demo toggle system**: `src/demo/test_demo.h` contains `#define XXX_DEMO` switches — uncomment ONE to run that demo. Currently `ALG_DEMO` is active.
- **Static lib dependencies**: `Debug/` contains `.a` files — pre-compiled algorithm/bootstrap libraries
- **Vector table**: Stored in `vector_table.o(.rodata*)` section, placed at eFlash entry via `KEEP()` in linkmap
- **BSS padding**: `.bss` section gets +0x08 bytes padding (alignment guard)
- **Text fill**: `.text` section filled with `0xbebe` pattern (debug signature)

## COMMANDS

```bash
# Build: Eclipse CDT managed build (Project → Build)
# Or from CLI:
make -C Debug all          # Using generated makefiles

# Flash & Debug: GDB with JTAG
# 1. Connect JTAG debugger, start OpenOCD/gdbserver on port 3333
# 2. Run GDB with gdbinit:
ccore-gdb Debug/CUni360S-Z_Demo.elf -x gdbinit

# Flash via TCL scripts (alternative):
# Edit gdbinit to uncomment monitor script lines for flash_erase.tcl / flash_pro.tcl
```

## NOTES

- **`.metadata/`**: Eclipse workspace state — do NOT version control or edit
- **`Debug/`**: Contains build artifacts AND mirror source tree for debugging — generated, don't edit
- **Source encoding**: Chinese comments are GBK/GB2312 — set editor encoding accordingly
- **No RTOS**: Bare-metal `while(1)` super-loop architecture
- **Static libs**: Algorithm/bootstrap code linked from `.a` files in `Debug/` — source not included in SDK
- **`SCI_BT`**: UART1 named "SCI_BT" (Bluetooth SCI) — SCI2 is the main debug UART at 115200 baud
- **Card power**: `CARD0` = ICC slot, `CARD1` = second card slot — voltage selectable via `CPM_SLPCFGR` bits