Mengimplementasikan properti sistem sebagai API

Properti sistem menyediakan cara mudah untuk membagikan informasi, biasanya konfigurasi, di seluruh sistem. Setiap partisi dapat menggunakan properti sistemnya sendiri secara internal. Masalah dapat terjadi saat properti diakses di seluruh partisi, seperti /vendor yang mengakses properti yang ditentukan /system. Sejak Android 8.0, beberapa partisi, seperti /system, dapat diupgrade, sementara /vendor dibiarkan tidak berubah. Karena properti sistem hanyalah kamus global pasangan nilai kunci string tanpa skema, properti sulit distabilkan. Partisi /system dapat mengubah atau menghapus properti yang bergantung pada partisi /vendor tanpa pemberitahuan apa pun.

Mulai rilis Android 10, properti sistem yang diakses di seluruh partisi diskematisasikan ke dalam file Deskripsi Sysprop, dan API untuk mengakses properti dibuat sebagai fungsi konkret untuk C++ dan Rust, serta class untuk Java. API ini lebih mudah digunakan karena tidak memerlukan string ajaib (seperti ro.build.date) untuk akses, dan karena dapat diketik secara statis. Stabilitas ABI juga diperiksa pada waktu build, dan build akan gagal jika terjadi perubahan yang tidak kompatibel. Pemeriksaan ini berfungsi sebagai antarmuka yang ditentukan secara eksplisit antar-partisi. API ini juga dapat memberikan konsistensi antara Rust, Java, dan C++.

Menentukan properti sistem sebagai API

Tentukan properti sistem sebagai API dengan file Deskripsi Sysprop (.sysprop), yang menggunakan TextFormat protobuf, dengan skema berikut:

// File: sysprop.proto

syntax = "proto3";

package sysprop;

enum Access {
  Readonly = 0;
  Writeonce = 1;
  ReadWrite = 2;
}

enum Owner {
  Platform = 0;
  Vendor = 1;
  Odm = 2;
}

enum Scope {
  Public = 0;
  Internal = 2;
}

enum Type {
  Boolean = 0;
  Integer = 1;
  Long = 2;
  Double = 3;
  String = 4;
  Enum = 5;
  UInt = 6;
  ULong = 7;

  BooleanList = 20;
  IntegerList = 21;
  LongList = 22;
  DoubleList = 23;
  StringList = 24;
  EnumList = 25;
  UIntList = 26;
  ULongList = 27;
}

message Property {
  string api_name = 1;
  Type type = 2;
  Access access = 3;
  Scope scope = 4;
  string prop_name = 5;
  string enum_values = 6;
  bool integer_as_bool = 7;
  string legacy_prop_name = 8;
}

message Properties {
  Owner owner = 1;
  string module = 2;
  repeated Property prop = 3;
}

Satu file Deskripsi Sysprop berisi satu pesan properti, yang mendeskripsikan serangkaian properti. Arti kolomnya adalah sebagai berikut.

Arti kolom pesan Property adalah sebagai berikut.

Setiap jenis properti dipetakan ke jenis berikut di C++, Java, dan Rust.

Berikut adalah contoh file Deskripsi Sysprop yang menentukan tiga properti:

# File: android/sysprop/PlatformProperties.sysprop

owner: Platform
module: "android.sysprop.PlatformProperties"
prop {
    api_name: "build_date"
    type: String
    prop_name: "ro.build.date"
    scope: Public
    access: Readonly
}
prop {
    api_name: "date_utc"
    type: Integer
    prop_name: "ro.build.date_utc"
    scope: Internal
    access: Readonly
}
prop {
    api_name: "device_status"
    type: Enum
    enum_values: "on|off|unknown"
    prop_name: "device.status"
    scope: Public
    access: ReadWrite
}

Menentukan library properti sistem

Sekarang Anda dapat menentukan modul sysprop_library dengan file Deskripsi Sysprop. sysprop_library berfungsi sebagai API untuk C++, Java, dan Rust. Sistem build secara internal menghasilkan satu rust_library, satu java_library, dan satu cc_library untuk setiap instance sysprop_library.

// File: Android.bp
sysprop_library {
    name: "PlatformProperties",
    srcs: ["android/sysprop/PlatformProperties.sysprop"],
    property_owner: "Platform",
    vendor_available: true,
}

Anda harus menyertakan file daftar API dalam sumber untuk pemeriksaan API. Untuk melakukannya, buat file API dan direktori api. Tempatkan direktori api di direktori yang sama dengan Android.bp. Nama file API adalah <module_name>-current.txt, <module_name>-latest.txt. <module_name>-current.txt menyimpan tanda tangan API dari kode sumber saat ini, dan <module_name>-latest.txt menyimpan tanda tangan API terbaru yang dibekukan. Sistem build memeriksa apakah API diubah dengan membandingkan file API ini dengan file API yang dihasilkan pada waktu build dan menampilkan pesan error serta petunjuk untuk memperbarui file current.txt jika current.txt tidak cocok dengan kode sumber. Berikut contoh organisasi file dan direktori:

├── api
│   ├── PlatformProperties-current.txt
│   └── PlatformProperties-latest.txt
└── Android.bp

Modul klien Rust, Java, dan C++ dapat ditautkan dengan sysprop_library untuk menggunakan API yang dihasilkan. Sistem build membuat link dari klien ke library C++, Java, dan Rust yang dihasilkan, sehingga memberikan akses klien ke API yang dihasilkan.

java_library {
    name: "JavaClient",
    srcs: ["foo/bar.java"],
    libs: ["PlatformProperties"],
}

cc_binary {
    name: "cc_client",
    srcs: ["baz.cpp"],
    shared_libs: ["libPlatformProperties"],
}

rust_binary {
    name: "rust_client",
    srcs: ["src/main.rs"],
    rustlibs: ["libplatformproperties_rust"],
}

Perhatikan bahwa nama library Rust dibuat dengan mengonversi nama sysprop_library menjadi huruf kecil, mengganti . dan - dengan _, lalu menambahkan lib di awal dan _rust di akhir.

Dalam contoh sebelumnya, Anda dapat mengakses properti yang ditentukan sebagai berikut.

Contoh Rust:

use platformproperties::DeviceStatusValues;

fn foo() -> Result<(), Error> {
  // Read "ro.build.date_utc". default value is -1.
  let date_utc = platformproperties::date_utc()?.unwrap_or_else(-1);

  // set "device.status" to "unknown" if "ro.build.date" is not set.
  if platformproperties::build_date()?.is_none() {
    platformproperties::set_device_status(DeviceStatusValues::UNKNOWN);
  }

  …
}

Contoh Java:

import android.sysprop.PlatformProperties;

…

static void foo() {
    …
    // read "ro.build.date_utc". default value is -1
    Integer dateUtc = PlatformProperties.date_utc().orElse(-1);

    // set "device.status" to "unknown" if "ro.build.date" is not set
    if (!PlatformProperties.build_date().isPresent()) {
        PlatformProperties.device_status(
            PlatformProperties.device_status_values.UNKNOWN
        );
    }
    …
}
…

Contoh C++:

#include <android/sysprop/PlatformProperties.sysprop.h>
using namespace android::sysprop;

…

void bar() {
    …
    // read "ro.build.date". default value is "(unknown)"
    std::string build_date = PlatformProperties::build_date().value_or("(unknown)");

    // set "device.status" to "on" if it's "unknown" or not set
    using PlatformProperties::device_status_values;
    auto status = PlatformProperties::device_status();
    if (!status.has_value() || status.value() == device_status_values::UNKNOWN) {
        PlatformProperties::device_status(device_status_values::ON);
    }
    …
}
…