Skip to content

CLI for SidePulse

Python
6.6 KB
Raw Blame
#!/usr/bin/env python3
"""macOS: write an existing LEDS.LED on an unmounted, single-FAT FAT12 disk.

    sudo python3 scripts/write_led_raw.py /dev/rdisk4 '#ff00ff'
    sudo python3 scripts/write_led_raw.py /dev/disk4 - < animation.LED

Only whole devices <= 300,000 bytes are accepted. No mounting or allocation.
"""

import argparse
import fcntl
import os
import plistlib
import re
import stat
import struct
import subprocess
import sys

MAX_DISK_BYTES = 300_000  # Decimal KB; deliberately stricter than 300 KiB.
SECTOR = 512
# macOS <sys/disk.h>: _IOR('d', 24, uint32_t), _IOR('d', 25, uint64_t).
DKIOCGETBLOCKSIZE = 0x40046418
DKIOCGETBLOCKCOUNT = 0x40086419


def require(condition, message):
    if not condition:
        raise ValueError(message)


def device_size(fd):
    """Query actual media capacity, never the size claimed by its FAT boot sector."""
    require(sys.platform == "darwin", "This utility requires macOS.")
    mode = os.fstat(fd).st_mode
    require(stat.S_ISBLK(mode) or stat.S_ISCHR(mode), "Not a disk device.")
    block = struct.unpack("=I", fcntl.ioctl(fd, DKIOCGETBLOCKSIZE, bytes(4)))[0]
    count = struct.unpack("=Q", fcntl.ioctl(fd, DKIOCGETBLOCKCOUNT, bytes(8)))[0]
    size = block * count
    require(0 < size <= MAX_DISK_BYTES,
            f"Refusing drive size {size:,} bytes; limit is {MAX_DISK_BYTES:,}.")
    require(block == SECTOR, "Only 512-byte device blocks are supported.")
    return size


def check_unmounted(device):
    result = subprocess.run(
        ["/usr/sbin/diskutil", "info", "-plist", device],
        check=True, capture_output=True,
    )
    info = plistlib.loads(result.stdout)
    require(info.get("DeviceIdentifier") == device.removeprefix("/dev/"),
            "Cannot verify device identity.")
    require(info.get("WholeDisk") is True, "Only whole disks are accepted.")
    # diskutil omits MountPoint for unmounted media; there is no Mounted key.
    require(info.get("MountPoint", "") == "",
            f"Drive must be unmounted first: diskutil unmountDisk {device}")


def read_sector(fd, offset):
    data = os.pread(fd, SECTOR, offset)
    require(len(data) == SECTOR, "Short disk read; refusing to write.")
    return data


def locate_led(fd, size):
    """Return data offset, directory-sector offset, and entry offset within it."""
    boot = read_sector(fd, 0)
    bps, spc, reserved, fats, entries, total = struct.unpack_from("<HBHBHH", boot, 11)
    fat_sectors = struct.unpack_from("<H", boot, 22)[0]
    hidden, total32 = struct.unpack_from("<II", boot, 28)
    total = total or total32
    require(boot[510:512] == b"\x55\xaa" and bps == SECTOR and fats == 1,
            "Expected FAT12 with 512-byte sectors and exactly one FAT.")
    require(hidden == 0 and reserved > 0 and entries > 0 and fat_sectors > 0,
            "Expected a FAT12 volume starting at sector zero.")
    require(spc in (1, 2, 4, 8, 16, 32, 64, 128), "Invalid cluster size.")
    root = reserved + fat_sectors
    data = root + (entries * 32 + SECTOR - 1) // SECTOR
    clusters = (total - data) // spc
    require(0 < total * SECTOR <= size and 0 < clusters < 4085,
            "Invalid FAT12 geometry or filesystem exceeds device size.")
    require(((clusters + 2) * 3 + 1) // 2 <= fat_sectors * SECTOR,
            "FAT is too small for this volume.")
    fat = os.pread(fd, fat_sectors * SECTOR, reserved * SECTOR)
    require(len(fat) == fat_sectors * SECTOR, "Short FAT read.")
    for index in range(entries):
        if index % 16 == 0:
            directory = read_sector(fd, root * SECTOR + index * 32)
        offset = (index % 16) * 32
        entry = directory[offset:offset + 32]
        if entry[0] == 0:
            break
        if entry[:11] != b"LEDS    LED" or entry[11] & 0x18:
            continue
        require(not entry[11] & 1, "LEDS.LED is read-only.")
        cluster = struct.unpack_from("<H", entry, 26)[0]
        require(2 <= cluster < clusters + 2, "Invalid LEDS.LED cluster.")
        packed = struct.unpack_from("<H", fat, cluster + cluster // 2)[0]
        next_cluster = (packed >> (4 if cluster & 1 else 0)) & 0xFFF
        require(next_cluster >= 0xFF8 or
                (2 <= next_cluster < clusters + 2 and next_cluster != cluster),
                "LEDS.LED cluster is unallocated or invalid.")
        return ((data + (cluster - 2) * spc) * SECTOR,
                (root + index // 16) * SECTOR, offset)
    raise ValueError("Existing LEDS.LED not found in the root directory.")


def write_led(device, text):
    require(sys.platform == "darwin", "This utility requires macOS.")
    match = re.fullmatch(r"/dev/r?(disk[0-9]+)", device)
    require(match is not None, "Use a whole /dev/diskN or /dev/rdiskN; no partitions.")
    payload = text.encode("utf-8")
    require(0 < len(payload) <= SECTOR and len(text.splitlines()) <= 20,
            "LED program must contain 1–512 bytes and at most 20 lines.")
    require("\0" not in text, "LED program must not contain NUL bytes.")
    buffered = "/dev/" + match.group(1)
    check_unmounted(buffered)
    # No symlinks, creation or truncation. Retain this descriptor for all I/O.
    fd = os.open(device, os.O_RDWR | os.O_NOFOLLOW)
    try:
        size = device_size(fd)
        data_offset, root_offset, entry_offset = locate_led(fd, size)
        directory = bytearray(read_sector(fd, root_offset))
        struct.pack_into("<I", directory, entry_offset + 28, len(payload))
        # Data first, file size last. Preserve the existing allocation and all
        # other directory entries. Raw devices require whole-sector writes.
        for offset, sector in ((data_offset, payload.ljust(SECTOR, b"\0")),
                               (root_offset, directory)):
            check_unmounted(buffered)
            require(device_size(fd) == size, "Device capacity changed; refusing write.")
            require(0 <= offset <= size - SECTOR and offset % SECTOR == 0,
                    "Write would be outside the device or unaligned.")
            require(os.pwrite(fd, sector, offset) == SECTOR, "Short disk write.")
            os.fsync(fd)
    finally:
        os.close(fd)


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("device", help="whole /dev/diskN or /dev/rdiskN")
    parser.add_argument("program", help="LED text (supports \\n), or - to read stdin")
    args = parser.parse_args()
    try:
        text = (sys.stdin.read(513) if args.program == "-"
                else args.program.replace("\\n", "\n"))
        write_led(args.device, text)
    except (OSError, ValueError, subprocess.SubprocessError) as exc:
        parser.exit(1, f"error: {exc}\n")
    print(f"Wrote LEDS.LED to {args.device}")


if __name__ == "__main__":
    main()