Diosix 개발하기
안전성 > 보안 > 정확성 > 유지보수성 순으로 우선시합니다. 자기 문서화되고, 메모리 안전하며, 엄격히 제한된 관용적 Zig 0.17.0 및 RISC-V 어셈블리를 작성하여 모든 변경 사항이 사전 커밋 재작업 없이 첫 번째 검토에서 reviewing-diosix를 통과하도록 합니다.
핵심 명령
- 작동 가능하고 완전하며 빌드 가능한 코드 (기본 요건): 모든 변경 사항은 루트 VM/하이퍼바이저 빌드와 호스트 단위 테스트 스위트(
./scripts/build.sh및./scripts/build.sh test) 모두에서 깔끔하게 컴파일되어야 합니다. 깨진 코드, 스텁TODO플레이스홀더, 모의 생산 경로, 또는 부분적으로 구현된 기능을 남겨 두지 마십시오. - 줄 및 파일 제한 (하위 폴더로 구성, 자르지 않음): 모든 코드와 주석은 <= 80열로 줄 바꿈합니다. 소스 파일은 <= 500줄로 유지합니다. 파일이 500줄을 초과하면 기능이나 테스트를 절대 축소하지 말고 전용 하위 폴더(
panes/vm.zig,vm/run.zig,tests/gui.zig)로 분해하고, 평면적인prefix_subname.zig파일(panes_vm.zig,vm_run.zig,tests_gui.zig)을 늘리지 마십시오. 모든 하위 모듈을 상위 모듈의test블록에 연결합니다(_ = @import("vm/run.zig");). - 접두사-밑줄 파일명 대신 하위 폴더 및 복사-붙여넣기 금지: 프로젝트, 디렉터리 또는 형제 접두사가 없는 간결한
snake_case파일명을 사용합니다(diosix_api.zig가 아닌api.zig,diosix-alsa-init.c가 아닌main.c,vm_info.zig가 아닌vm/info.zig,tests_nav.zig가 아닌tests/nav.zig). 공유 기본 요소(Spinlock, 페이지 정렬 계산, 경로 순회 검증기, ABI 상수 등)를 모듈 간에 절대 복제하지 말고,hypervisor/interface/,hypervisor/core/atomic.zig또는common.zig에서 가져옵니다. - 관용적 디스패치: 명령, 플래그 또는 구성 키에 대해
if (std.mem.eql(...)) else if (...)체인을 작성하지 마십시오.enum을 정의하고,std.meta.stringToEnum(EnumType, slice)로 구문 분석한 다음switch로 디스패치합니다. - 명시적 고정폭 ABI 타입, 소문자 16진수 및 명명된 비트마스크: 모든 ABI/하드웨어 구조체(
extern struct,packed struct) 및 64비트 게스트 레지스터 상태에 명시적 고정폭 타입(u64,u32,u16,u8)을 사용하고,usize나 Cunsigned long을 사용하지 마십시오.@min/@max에서 초기화된 로컬 변수는 항상 컴파일 타임 리터럴(const w: usize = @min(n, 1280);)로 주석을 달아 Zig가 나중에 오버플로우되는 좁은 정수 타입(u11)을 추론하지 못하게 합니다. 모든 16진수 리터럴은 소문자로 작성하고(0xfff,0xffff_ffff,0xFFF사용 금지), 매직 비트마스크/오프셋((vaddr & 0xfff) > 0xffc)을 명명된 상수와 자기 문서화 헬퍼(PAGE_OFFSET_MASK,crossesPageBoundary(vaddr, @sizeOf(u32)))로 대체합니다. - 정적 추측보다 동적 할당: 힙 초기화 전에 실행되는 초기 M-모드 부트 코드만 고정 정적 버퍼를 사용할 수 있습니다. 할당자가 사용 가능해지면, 고정 스택 버퍼 크기를 추측하는 대신 동적으로 버퍼를 할당하고 늘립니다(예:
var buf: [4096]u8지양). - 메모리 소유권 및 정리: 모든 할당(
alloc,create,dupe,print,mmap)은 즉시defer또는errdefer와 쌍을 이룹니다. 해제된 게스트 페이지 및 암호화 비밀은 0으로 설정합니다(std.crypto.secureZero). - 엔터프라이즈 하이퍼바이저 격리: 게스트 입력 또는 상태로 인해 M-모드에서 절대 패닉하지 말고, SBI 오류를 반환하거나 문제를 일으킨 게스트 하위 트리를 종료합니다. 공유 게스트 메모리는 검증 전에 하이퍼바이저 소유 메모리로 한 번 복사(
@memcpy)하여 이중 가져오기(TOCTOU) 취약점을 방지합니다. - 코드의 메커니즘, 빌드/런타임 구성의 정책: Zig 코드에 정책 수준 설정이나 조정 가능한 기본값을 하드코딩하지 마십시오. 조정 가능한 항목과 설정은 빌드 시간 구성(
build.zig옵션 /boot/hypervisor.conf) 또는 런타임 구성 파일(/etc/diosix/*.toml,key = "value"를 80열 이하의 단일 줄로 유지)로 이동합니다. - 빌드 시점에 바이너리 및 이미지 빌드, Zig에서 동적으로 생성하지 않음: Zig 런타임에 ELF 바이너리, 머신 코드 심, 또는 미디어 이미지를 단어 단위로 조립하는 것을 피합니다. 심은 빌드 시점에 컴파일되는 어셈블리 또는 Zig 소스 파일에 유지하고, 전용 스크립트를 사용하여 미디어 이미지를 빌드하며, 생성된 빌드 출력물을
tools/overlay-common/안에 두지 마십시오(.zig-cache/overlay-dynamic/사용). - 동일 위치 단위 테스트 및 별도 통합 테스트: 단위
test블록은 테스트하는 소스 파일 내에 배치합니다(std.testing.refAllDecls(@This())호출). 여러 구성 요소의 통합 테스트는 전용tests/디렉터리에 배치합니다. - 레거시 폴백 누적 없는 하위 호환성: 외부 계약(SBI 하이퍼콜 ABI,
/dev/diosixioctls, 문서화된dsxCLI 명령/JSON 스키마, 사용자 작성/etc/diosix/*.toml파일)에 대한 호환성은 유지하지만, 동일 버전의 내부 배관을 위해 다중 경로 폴백 배열(DEFAULT_GUEST_CANDIDATES)을 절대 누적하지 마십시오. 생산자와 소비자가 이 리포지토리에서 함께 제공될 때, 단일 정규 경로 또는 심볼을 사용하도록 모든 트리 내 생산자, 소비자 및 테스트를 원자적으로 업데이트하고, 영구 디스크 레이아웃 업그레이드는 부트/설치 경계에서 한 번 처리하며 과거 경로를 영원히 탐색하지 마십시오. - 확실하지 않을 때는 중단하고 수석 관리자에게 문의: 아키텍처 결정, 모호한 요구 사항 또는 누락된 하위 시스템 기능에 대해 추측하지 마십시오. 진행 전에 중단하고 수석 관리자에게 문의하십시오.
M-모드 대 U-모드 실행 환경
| 측면 | M-모드 하이퍼바이저 (hypervisor/) | U-모드 도구 (tools/) |
|---|---|---|
| 대상 | riscv64-freestanding-none | riscv64-linux-musl (또는 테스트에서 호스트) |
| 힙 전 부트 | entry.s의 코어당 정적 슬래브(0..31) | N/A (OS 프로세스 환경이 main에서 준비됨) |
| 할당자 | 코어당 pcore.this().allocator.allocator() | std.heap.SafeAllocator / page_allocator / ArenaAllocator |
| 충돌 정책 | 게스트 입력에 대해 절대 패닉하지 않음; 문제를 일으킨 게스트 VM을 격리 및 종료 | 설명적인 오류 및 깔끔한 종료 코드 반환 |
| 하드웨어 액세스 | 직접 CSR/MMIO (호스트 단위 테스트의 경우 if (is_test)로 보호해야 함) | /dev/diosix ioctls (api.zig), DRM/evdev, Linux 시스템 콜 |
집중 참조 가이드
코드를 작성하거나 수정하기 전에 관련 참조 파일을 읽으십시오:
- Zig 0.17.0 관용구 및 내장 함수:
최신 Zig 0.17 문법 (
@backingInt,@splat,allocator.print,SafeAllocator,stringToEnum,extern struct용@ptrCast, 고정폭 ABI 타입,@min타입 주석, 후행 쉼표가 있는 80열 서식, 빌드 캐시 순수성). - 메모리 관리 및 동적 버퍼:
M-모드 대 U-모드 할당자 패턴, 동적 버퍼 증가,
defer/errdefer규율, 비밀 영점화, 출력 포인터 초기화. - 아키텍처 및 TigerStyle: 완전한 기능 구현, 단위 테스트 손실 없는 모듈식 파일 분할, 복사-붙여넣기 중복 제로, 제한된 루프, 어설션 쌍, 오버레이/구성 위생.
- RISC-V 및 엔터프라이즈 하이퍼바이저: RV64 어셈블리 규칙, CSR 모킹, 폭발 반경 제한, 이중 가져오기 방지 패턴, IRQ-안전 스핀락 순서, G-스테이지/PMP 격리.