일반 시스템 이미지

일반 시스템 이미지(GSI)는 Android 기기용으로 구성이 조정된 시스템 이미지입니다. Android 9 이상 버전을 실행하는 모든 Android 기기에서 실행 가능하고 수정되지 않은 Android 오픈소스 프로젝트(AOSP) 코드를 사용하는 순수 Android 구현으로 간주됩니다.

GSI는 VTS 및 CTS-on-GSI 테스트를 실행하는 데 사용됩니다. Android 기기의 시스템 이미지는 GSI로 대체된 다음 공급업체 테스트 모음(VTS) 및 호환성 테스트 모음(CTS)으로 테스트되어 기기가 Android의 최신 버전에서 공급업체 인터페이스를 제대로 구현하는지 확인합니다.

참고: 이 도움말에서는 Android OEM 및 ROM 개발자를 위한 GSI 주제를 설명합니다. Android 앱 개발자를 위한 개발자 대상 GSI 세부정보는 developer.android.com을 참고하시기 바랍니다.

GSI를 시작하려면 다음 섹션에서 GSI 구성(및 허용되는 차이)과 유형에 관한 자세한 내용을 살펴보세요. GSI를 사용할 준비가 되면 대상 기기에 맞는 GSI를 다운로드 및 빌드한 다음 Android 기기로 GSI를 플래싱합니다.

GSI 구성 및 차이

현재 Android GSI 프로젝트는 다음과 같이 구성되어 있습니다.

• 트레블. GSI에는 AIDL 인터페이스 및 HIDL 인터페이스 지원을 비롯해 AIDL/HIDL 기반 아키텍처 변경사항(다른 명칭: 트레블)에 대한 완전한 지원이 포함되어 있습니다. HIDL 공급업체 인터페이스를 사용하는 모든 Android 기기에서 GSI를 사용할 수 있습니다. 자세한 내용은 아키텍처 리소스를 참고하세요.
• 파일 시스템. GSI는 ext4 파일 시스템을 사용합니다.

현재 Android GSI에는 다음과 같은 주요 차이점이 있습니다.

• CPU 아키텍처. 다양한 CPU 안내(ARM, x86 등) 및 CPU 비트율(32비트 또는 64비트)을 지원합니다.

트레블 적합성 테스트를 위한 GSI 타겟

준수 테스트에 사용되는 GSI는 기기가 출시되는 Android 버전에 따라 결정됩니다.

기기 유형	빌드 대상
Android 12가 탑재된 기기	gsi_$arch-user(서명됨)
Android 11이 탑재된 기기	gsi_$arch-user(서명됨)
Android 10이 탑재된 기기	gsi_$arch-user(서명됨)
Android 9이 탑재된 기기	gsi_$arch-userdebug

모든 GSI는 Android 12 코드베이스에서 빌드되며 각 CPU 아키텍처에는 해당 GSI 바이너리(GSI 빌드에서 빌드 대상 목록 참고)가 있습니다.

Android 12 GSI 변경사항

Android 12가 탑재되었거나 Android 12로 업데이트된 기기는 규정 준수 테스트에 Android 12 GSI를 사용해야 합니다. 이전 GSI에서 크게 바뀐 점은 다음과 같습니다.

• 대상 이름. 규정 준수 테스트의 GSI 대상 이름이 gsi_$arch로 변경됩니다. 대상 이름이 aosp_$arch인 GSI는 Android 앱 개발자를 위해 유지됩니다. CTS-on-GSI 테스트 계획도 공급업체 인터페이스 테스트에 맞춰 축소됩니다.
• 기존 GSI 단계적 중단. GSI 12에서는 트레블이 완전히 적용되지 않은 Android 8.0 또는 8.1 기기를 위한 해결 방법을 사용할 필요가 없습니다.
• Userdebug SEPolicy. GSI gsi_$arch에는 userdebug_plat_sepolicy.cil이 포함되어 있습니다. OEM별 vendor_boot-debug.img 또는 boot-debug.img를 플래시하면 /system/bin/init는 GSI system.img에서 userdebug_plat_sepolicy.cil을 로드합니다. 자세한 내용은 디버그 램디스크로 VTS 테스트하기를 참고하세요.

Android 11 GSI 변경사항

Android 11이 탑재되거나 Android 11로 업데이트된 기기는 규정 준수 테스트에 Android 11 GSI를 사용해야 합니다. 이전 GSI에서 크게 바뀐 점은 다음과 같습니다.

• system_ext 콘텐츠. Android 11은 새 파티션 system_ext를 정의합니다. GSI는 시스템 확장 프로그램 콘텐츠를 system/system_ext 폴더에 넣습니다.
• APEX. GSI에는 평면화된 APEX와 압축된 APEX가 모두 포함됩니다. 어떤 것을 사용할지는 런타임 시 공급업체 파티션의 시스템 속성 ro.apex.updatable에 의해 결정됩니다. 자세한 내용은 APEX 업데이트를 지원하도록 시스템 구성하기를 참고하세요.

Android 10 GSI 변경사항

Android 10을 탑재하거나 Android 10으로 업데이트된 기기는 규정 준수 테스트에 Android 10 GSI를 사용해야 합니다. 이전 GSI에서 크게 바뀐 점은 다음과 같습니다.

• 사용자 빌드. GSI는 Android 10에서 사용자 빌드를 사용합니다. Android 10에서는 CTS-on-GSI/VTS 규정 준수 테스트에 사용자 빌드 GSI를 사용할 수 있습니다. 자세한 내용은 디버그 램디스크로 VTS 테스트하기를 참고하세요.
• 촘촘한 형식. aosp_$arch 타겟이 있는 GSI는 촘촘한 형식으로 빌드됩니다. 필요한 경우 img2simg를 사용하여 촘촘한 GSI를 성긴 형식으로 변환할 수 있습니다.
• System-as-root. 이름이 aosp_$arch_a인 기존 GSI 빌드 타겟에 대한 지원은 단계적으로 중단되었습니다. Android 8 또는 8.1에서 ramdisk와 non-system-as-root가 포함된 Android 10으로 업그레이드된 기기는 기존 GSI aosp_$arch_ab를 사용하세요. 램디스크의 업그레이드된 init은 OEM system.img 및 system-as-root 레이아웃을 지원합니다.
• 자체 검사 부팅. GSI를 사용할 때는 기기를 잠금 해제하기만 하면 됩니다. 자체 검사 부팅을 사용 중지할 필요는 없습니다.

Android 9 GSI 변경사항

Android 9이 탑재되거나 Android 9으로 업데이트된 기기는 규정 준수 테스트에 Android 9 GSI를 사용해야 합니다. 이전 GSI에서 크게 바뀐 점은 다음과 같습니다.

• GSI 및 에뮬레이터 병합. GSI는 에뮬레이터 제품의 시스템 이미지로 구축됩니다(예: aosp_arm64 및 aosp_x86).
• System-as-root. 이전 버전의 Android에서 A/B 업데이트를 지원하지 않는 기기는 시스템 이미지를 /system 디렉터리 아래에 마운트할 수 있었습니다. Android 9에서 시스템 이미지의 루트는 기기의 루트로 마운트됩니다.
• 64비트 바인더 인터페이스. Android 8.x에서 32비트 GSI는 32비트 바인더 인터페이스를 사용했습니다. Android 9은 32비트 바인더 인터페이스를 지원하지 않으므로 32비트 GSI와 64비트 GSI 모두 64비트 바인더 인터페이스를 사용합니다.
• VNDK 시행. Android 8.1에서 VNDK는 선택사항이었습니다. Android 9에서는 VNDK가 필수이므로 BOARD_VNDK_VERSION을 설정해야 합니다.
• 호환 가능한 시스템 속성. Android 9은 호환되는 시스템 속성(PRODUCT_COMPATIBLE_PROPERTY_OVERRIDE := true)에 대한 액세스 검사를 사용 설정합니다.

Android 9 Keymaster 변경사항

이전 버전의 Android에서는 실행 중인 시스템에서 보고한 버전 정보(ro.build.version.release 및 ro.build.version.security_patch)가 부트로더에서 보고한 버전 정보와 일치하는지 확인하려면 Keymaster 3 이하를 구현하는 기기가 필요했습니다. 이러한 정보는 일반적으로 부팅 이미지 헤더에서 가져옵니다.

Android 9 이상에서 벤더가 GSI를 부팅할 수 있도록 요구사항이 변경되었습니다. 특히 Keymaster는 GSI에서 보고한 버전 정보가 공급업체의 부트로더가 보고한 버전 정보와 일치하지 않을 수 있으므로 인증을 수행하지 말아야 합니다. Keymaster 3 이하를 구현하는 기기의 경우 인증을 건너뛰거나 Keymaster 4로 업그레이드하도록 Keymaster 구현을 수정해야 합니다. Keymaster에 대한 자세한 내용은 하드웨어 지원 키 저장소를 참고하세요.

GSI 다운로드하기

ci.android.com의 AOSP Continuous Integration(CI) 웹사이트에서 사전 빌드된 GSI를 다운로드할 수 있습니다. 원하는 하드웨어 플랫폼의 GSI 유형을 다운로드할 수 없다면 다음 섹션에서 특정 타겟의 GSI 빌드에 관한 자세한 내용을 참고하세요.

GSI 빌드하기

Android 9 이후의 각 Android 버전에는 AOSP에 DESSERT-gsi라는 GSI 브랜치가 있습니다. 예를 들어 android12-gsi는 Android 12의 GSI 브랜치입니다. GSI 브랜치에는 보안 패치와 GSI 패치가 모두 적용된 Android 콘텐츠가 포함되어 있습니다.

GSI를 빌드하려면 GSI 브랜치에서 다운로드하고 GSI 빌드 대상을 선택하여 Android 소스 트리를 설정합니다. 아래의 빌드 대상 표를 사용하여 기기에 맞는 GSI 버전을 확인하세요. 빌드가 완료되면 GSI가 시스템 이미지(system.img)가 되며 출력 폴더 out/target/product/generic_arm64에 나타납니다.

예를 들어 GSI 빌드 대상 gsi_arm64-userdebug를 GSI 브랜치 android12-gsi에서 빌드하려면 다음 명령을 실행합니다.

$ repo init -u https://android.googlesource.com/platform/manifest -b android12-gsi
$ repo sync -cq
$ source build/envsetup.sh
$ lunch gsi_arm64-userdebug
$ make -j4

Android GSI 빌드 타겟

다음 GSI 빌드 타겟은 Android 9 이상을 탑재하여 출시된 기기에 사용됩니다.

GSI 이름	CPU arch	바인더 인터페이스 비트율	System-as-root	빌드 대상
gsi_arm	ARM	64	예	gsi_arm-user gsi_arm-userdebug
gsi_arm64	ARM64	64	예	gsi_arm64-user gsi_arm64-userdebug
gsi_x86	x86	64	예	gsi_x86-user gsi_x86-userdebug
gsi_x86_64	x86-64	64	예	gsi_x86_64-user gsi_x86_64-userdebug

GSI 플래싱 요구사항

Android 기기는 디자인이 다르기 때문에 모든 기기에 적용시킬 수 있도록 GSI를 플래싱할 수 있는 일반적인 명령어나 지침은 없습니다. Android 기기 제조업체에 명확한 플래싱 방법을 문의해 보세요. 다음 단계를 일반적인 가이드라인으로 사용하세요.

1. 기기에 다음 항목이 있는지 확인합니다.
   • 트레블 조정됨
   • 기기를 잠금 해제하는 방법(fastboot를 사용하여 플래시 가능)
   • fastboot를 통해 플래싱할 수 있는 잠금 해제 상태(fastboot 최신 버전을 사용하려면 Android 소스 트리에서 빌드할 것)
2. 현재 시스템 파티션을 지운 다음 GSI를 시스템 파티션으로 플래시합니다.
3. 사용자 데이터를 지우고 다른 필요한 파티션(예: 사용자 데이터 및 시스템 파티션)에서 데이터를 지웁니다.
4. 기기를 재부팅합니다.

예를 들어 GSI를 Pixel 기기로 플래시하는 방법은 다음과 같습니다.

1. fastboot 모드로 부팅하고 부트로더를 잠금 해제합니다.
2. fastbootd를 지원하는 기기도 다음과 같은 방법을 사용해 fastbootd로 부팅해야 합니다.

   $ fastboot reboot fastboot

3. GSI를 삭제하고 시스템 파티션에 플래싱합니다.

   $ fastboot erase system
   $ fastboot flash system system.img

4. 사용자 데이터를 지우고 다른 필요한 파티션(예: 사용자 데이터 및 시스템 파티션)에서 데이터를 지웁니다.

   $ fastboot -w

5. 재부팅:

   $ fastboot reboot

시스템 파티션이 더 작은 Android 10 이상 기기의 경우 GSI를 플래시할 때 다음과 같은 오류 메시지가 표시될 수 있습니다.

    Resizing 'system_a'    FAILED (remote: 'Not enough space to resize partition')
    fastboot: error: Command failed

다음 명령어를 사용하여 제품 파티션을 삭제하고 시스템 파티션을 위한 공간을 확보합니다. 이를 통해 GSI를 플래시하기 위한 추가 공간이 제공됩니다.

$ fastboot delete-logical-partition product_a

접미사 _a는 시스템 파티션의 슬롯 ID와 일치해야 합니다(이 예에서는 system_a).

GSI에 참여하기

Android는 GSI 개발에 대한 여러분의 참여를 환영합니다. 다음과 같은 방법으로 GSI에 참여할 수 있습니다.

• GSI 패치 만들기. DESSERT-gsi는 개발 브랜치가 아니고 AOSP 마스터 브랜치에서 선택(cherrypick)한 것만 허용하므로 GSI 패치를 제출하려면 다음을 실행해야 합니다.
  1. 패치를 AOSP master 브랜치에 제출합니다.
  2. 패치를 DESSERT-gsi에 선택 적용(cherrypick)합니다.
  3. 버그를 제출하여 선택(cherrypick)한 항목을 검토합니다.
• GSI 버그를 신고하거나 다른 제안을 합니다. 버그 신고의 안내를 검토한 다음 GSI 버그를 둘러보거나 신고합니다.

팁

adb를 사용하여 탐색 메뉴 모드 변경

GSI로 부팅할 때 탐색 메뉴 모드는 공급업체 재정의로 구성됩니다. 런타임 시 다음 adb 명령어를 실행하여 탐색 메뉴 모드를 변경할 수 있습니다.

adb exec-out cmd overlay enable-exclusive com.android.internal.systemui.navbar.mode

여기서 mode는 threebutton, twobutton, gestural 등일 수 있습니다.