partitionslot

Imported from openharmony/drivers_peripheral (partitionslot/AGENTS.md). Install upstream with npx skills add openharmony/drivers_peripheral --skill partitionslot. Copyright stays with the author.

AGENTS.md — drivers/peripheral/partitionslot

Guidance for coding agents working in the OpenHarmony drivers_peripheral_partitionslot component — the server-side implementation of the PartitionSlot HDI (A/B multi-slot boot partition management). Read this before editing any file under drivers/peripheral/partitionslot/.

Scope: component root (drivers/peripheral/partitionslot), inside the drivers/peripheral git repository. The HDI interface (IDL, generated proxy/stub) lives in a separate repo: drivers/interface/partitionslot.

1. Code map

1.1 What this component owns

The PartitionSlot HDI service implementation, offering four APIs:

• GetCurrentSlot — which partition slot the board booted from, and how many slots exist,
• GetSlotSuffix — slot index → partition-name suffix ("_a" / "_b"),
• SetActiveSlot — switch the slot the device boots from next,
• SetSlotUnbootable — mark a slot unbootable.

Slot state is persisted directly in the bootctrl partition (/dev/block/by-name/bootctrl); the slot count comes from the system parameter ohos.boot.bootslots (default 1). Typical consumer: the begetctl partitionslot tool in base/startup/init (services/begetctl/partitionslot.cpp, subcommands getslot / getsuffix / setactive / setunboot; setactive is listed in that repo's AGENTS.md as a destructive command).

1.2 Runtime call chain (dependency direction: top calls bottom; never reverse)

caller (e.g. begetctl partitionslot in startup_init)
  → libpartitionslot_proxy_1.0        generated proxy (drivers/interface repo)
  → HDF dispatch in partitionslot_host  HdfSBuf ↔ MessageParcel, forwards to stub
  → PartitionSlotImpl                  implements IPartitionSlot (libpartition_slot_service_1.0)
  → PartitionSlotManager               DelayedSingleton, all real logic (libpartition_slot_manager)
  → /dev/block/by-name/bootctrl        raw open/lseek/read/write

Deployment comes from per-product HDF config (vendor/<vendor>/<product>/hdf_config/uhdf/device_info.hcs, section partitionslot): host partitionslot_host, service name partition_slot_service, driver libpartitionslot_driver.z.so, preload = 2 (on-demand — IPartitionSlot::Get(true) triggers the load). The host process uid/gid also comes from this config (rk3568: uid useriam, gid ["useriam", "update"]) — check it when debugging bootctrl permission errors.

High-risk / frequently-changed paths (treat changes here with extra care): hal/src/partitionslot_manager.cpp (MISC_PARTITION_* disk-layout constants, slot numbering), bundle.json (inner_kits is the downstream-facing surface).

Nested guidance: none in this component. The interface side has its own drivers/interface/partitionslot/AGENTS.md (ZH mirror AGENTS_zh.md).

2. Knowledge routing — read before you edit

Before editing any file, state to yourself: (1) the task category, (2) which row of §2.1 you loaded (plus the IDL row whenever API semantics are involved), and (3) which §3 constraint applies. If you cannot answer all three, stop and read.

2.1 Task-based routing

2.2 Vocabulary routing (when a term appears in a task/log/issue/API)

3. Constraints and boundaries (do not break without escalation)

3.1 Architecture invariants (hard rules)

1. The bootctrl disk layout is a bootloader contract. Active slot @ offset 1024 (4 bytes), unbootable slot @ offset 1028 (4 bytes) — the MISC_PARTITION_* constants. Never change offsets/sizes; bootloader and updater agree on this format.
2. IPC signatures are frozen here. This component only implements the interface. Signature/semantic changes belong in drivers/interface/partitionslot (IDL, separate repo, own review rules).
3. Slot numbering quirk. The implementation (and tests) treat 2 as slot B (UPDATE_PARTITION_B = 2): GetSlotSuffix(2) → "_b", everything else → "_a" — while the IDL docs say 0=A, 1=B, N=N. Never "fix" this locally; numbering semantics must be aligned with the interface repo first.
4. Return-value contract. 0 = success, negative = failure; -1 specifically means the board does not support A/B partitions. Note: HAL GetCurrentSlot returns 0 even when the bootctrl read fails (currentSlot is then -1).

3.2 Do-not rules

• Do not modify the MISC_PARTITION_* constants (§3.1.1).
• Do not run SetActiveSlot / SetSlotUnbootable (or unittest cases 003/004) against real hardware unless the task explicitly asks — they change persistent boot state; case 003 restores the active slot, case 004 leaves the unbootable mark written.
• Do not change install_images casually: hal lib → system + updater images; both hdi_service libs → chipset image.
• Do not edit generated code under out/<product>/gen/ — regenerate by building instead.
• Do not add a source file without wiring it into the matching BUILD.gn sources — it is silently not built otherwise.
• Do not remove the Apache 2.0 license header.

3.3 Ask before

• Any change to bundle.json inner_kits or headers under hal/include/ — libpartition_slot_manager is linked by downstream components.
• Any semantic change to SetActiveSlot / SetSlotUnbootable — boot behavior, needs maintainer sign-off.
• Changing slot numbering (§3.1.3) — align with the interface repo.

3.4 Local conventions

• hal/BUILD.gn and hdi_service/BUILD.gn reference this component via long relative paths ("../../../../drivers/peripheral/partitionslot/...") instead of //drivers/... labels — keep the local style when editing.
• Logging: hal uses hilog macros (HILOG_*, LOG_DOMAIN 0xD002500, tag hdf_partitionslot_manager); hdi_service uses HDF_LOG* (tag hdf_partitionslot_impl).
• New files need the Apache 2.0 header, matching existing files.

3.5 Common agent failure modes here

• Running build.sh from this directory — it only works from the OHOS source root (ancestor containing build.sh).
• Assuming slot 1 = B from the IDL docs while the implementation uses 2.
• Expecting the unittest to pass off-device — it needs a real HDF environment and /dev/block/by-name/bootctrl; without a device only compile/link checks are possible.

4. Verification loop

4.1 Build the component (from the OHOS source root, not this directory)

./build.sh --product-name rk3568 --build-target partitionslot_entry        # everything: hal + hdi_service
./build.sh --product-name rk3568 --build-target libpartition_slot_manager  # HAL inner_kit only
./build.sh --product-name rk3568 --build-target hdf_partitionslot_service  # both hdi_service libs

4.2 Build & run unit tests

./build.sh --product-name rk3568 --build-target partitionslot_hdi_test
# binary: out/rk3568/tests/unittest/drivers_peripheral_partitionslot/drivers_peripheral_partition_slot/partitionslot_hdi_test

The test loads the service via IDeviceManager::LoadDevice("partition_slot_service") and drives all four APIs through the proxy over real HDF IPC — it requires a device (or full HDF environment) with /dev/block/by-name/bootctrl. Building the target alone already verifies the compile/link chain end to end.

4.3 Minimum checks before declaring done

• --build-target partitionslot_hdi_test build succeeds (§4.2 command).
• git diff touches no MISC_PARTITION_* constant, no bundle.json inner_kits, no install_images (unless explicitly approved, §3.3).
• If HDI behavior changed: state for each of the 4 test cases whether the expected result changes.
• New files are wired into BUILD.gn and carry the license header.
• No new compile warnings in the files you touched.

4.4 Done definition & final response

Report: (1) files changed with path:line of the key edits, (2) which §3 constraint applied and how it was respected, (3) the exact build/test commands run and their pass/fail result. If the build/tests could not run (no toolchain or device), say so explicitly, mark the work NOT VERIFIED, and list the commands a human should run instead — do not claim success without evidence.