vfs — управление виртуальной файловой системой

Модуль vfs содержит функции для создания объектов файловых систем и их монтирования/размонтирования в виртуальной файловой системе.

Монтирование файловых систем

Некоторые порты предоставляют виртуальную файловую систему (VFS) и возможность монтировать в ней несколько «реальных» файловых систем. Объекты файловых систем можно монтировать либо в корень VFS, либо в подкаталог, расположенный в корне. Это обеспечивает динамическую и гибкую настройку файловой системы, видимой программами на Python. Порты, обладающие этой функциональностью, предоставляют функции mount() и umount(), а также, возможно, различные реализации файловых систем, представленные классами VFS.

vfs.mount(fsobj: Any, mount_point: str, *, readonly: bool = False) → None

Монтирует объект файловой системы fsobj в место VFS, заданное строкой mount_point. fsobj может быть объектом VFS, имеющим метод mount(), либо блочным устройством. Если это блочное устройство, тип файловой системы определяется автоматически (если файловая система не распознана, возбуждается исключение). mount_point может быть '/' для монтирования fsobj в корень, либо '/<name>' для монтирования в подкаталог под корнем.

Если readonly равно True, файловая система монтируется только для чтения.

В процессе монтирования у объекта файловой системы вызывается метод mount().

Возбуждает OSError(EPERM), если mount_point уже смонтирован.

vfs.mount() → List[Tuple[Any, str]]

При вызове mount() без аргументов возвращает список кортежей, представляющих все активные точки монтирования.

Возвращаемый список имеет вид [(fsobj, mount_point), …].

vfs.umount(mount_point: str | Any) → None

Размонтирует файловую систему. mount_point может быть строкой с именем места монтирования либо ранее смонтированным объектом файловой системы. В процессе размонтирования у объекта файловой системы вызывается метод umount().

Возбуждает OSError(EINVAL), если mount_point не найден.

class vfs.VfsFat(block_dev: AbstractBlockDev)

Создаёт объект файловой системы, использующий формат файловой системы FAT. Хранилище файловой системы FAT обеспечивается block_dev. Объекты, созданные этим конструктором, можно смонтировать с помощью mount().

static mkfs(block_dev: AbstractBlockDev) → None

Создаёт файловую систему FAT на block_dev.

class vfs.VfsRom(buffer: bytes | bytearray | memoryview)

Создаёт объект файловой системы, использующий формат файловой системы только для чтения ROMFS. buffer должен быть объектом, поддерживающим протокол буфера (bytes, bytearray или memoryview) и содержащим корректный образ ROMFS.

Объекты, созданные этим конструктором, можно смонтировать с помощью mount().

Полное описание, включая способ сборки и развёртывания образов ROMFS с помощью mpremote, см. в Работа с ROMFS.

vfs.rom_ioctl(op: int, *args: Any) → Any

Низкоуровневый интерфейс для доступа к разделам постоянной памяти (ROM) устройства. Поддерживаются следующие операции:

Вызов	Поведение
rom_ioctl(1)	Возвращает количество доступных разделов ROM.
rom_ioctl(2, id)	Возвращает раздел id в виде memoryview.
rom_ioctl(3, id, length)	Стирает первые length байт раздела id в рамках подготовки к записи. Возвращает минимальное выравнивание записи в байтах.
rom_ioctl(4, id, offset, buf)	Записывает buf в раздел id по байтовому смещению offset.
rom_ioctl(5, id)	Завершает последовательность записи в раздел id (сбрасывает кэши и т. п.).

Эти операции обычно вызываются косвенно посредством mpremote при развёртывании образа ROMFS; большинству приложений не требуется вызывать их напрямую.

class vfs.VfsPosix(root: str | None = None)

Создаёт объект файловой системы, обращающийся к хостовой файловой системе POSIX. Если задан root, он должен быть путём в хостовой файловой системе, используемым в качестве корня объекта VfsPosix. В противном случае используется текущий каталог хостовой файловой системы.

Примечание

VfsPosix доступен только в Unix-порту MicroPython; в прошивке OpenMV Cam он отсутствует.

Блочные устройства

Блочное устройство — это объект, реализующий блочный протокол. Это позволяет устройству поддерживать файловые системы MicroPython. Физическое оборудование представляется определяемым пользователем классом. Класс AbstractBlockDev является шаблоном для проектирования такого класса: MicroPython фактически не предоставляет этот класс, но реальный класс блочного устройства должен реализовывать описанные ниже методы.

Конкретная реализация этого класса обычно обеспечивает доступ к памятеподобной функциональности части оборудования (например, флеш-памяти). Блочное устройство можно отформатировать в любую поддерживаемую файловую систему и смонтировать с помощью методов os.

Примеры реализаций блочных устройств, использующих два варианта блочного протокола, описанных ниже, см. в Работа с файловыми системами.

Простой и расширенный интерфейс

Существуют две совместимые сигнатуры методов readblocks и writeblocks (см. ниже), предназначенные для поддержки различных сценариев использования. Конкретное блочное устройство может реализовывать ту или иную форму либо обе одновременно. Вторая форма (с параметром смещения) называется «расширенным интерфейсом».

Некоторым файловым системам требуется больший контроль над операциями записи — например, запись в области меньше блока без стирания — и им нужно, чтобы блочное устройство поддерживало расширенный интерфейс.

class vfs.AbstractBlockDev

Шаблон документации для протокола блочного устройства. MicroPython фактически не предоставляет этот класс — он показан здесь лишь для документирования методов, которые должен реализовывать определяемый пользователем класс блочного устройства. Аргументы конструктора полностью зависят от реализации (обычно это такие вещи, как шина флеш-памяти, вывод выбора кристалла, размер сектора и т. п.).

readblocks(block_num: int, buf: bytearray) → None

readblocks(block_num: int, buf: bytearray, offset: int) → None

Читает байты из устройства в buf. Две перегрузки представляют простой и расширенный интерфейсы.

Простая форма (readblocks(block_num, buf)): читает целые блоки начиная с индекса блока block_num. len(buf) должно быть кратно размеру блока, а число прочитанных блоков равно len(buf) // block_size.

Расширенная форма (readblocks(block_num, buf, offset)): читает len(buf) байт — не обязательно целое число блоков — начиная с байтового смещения offset внутри блока block_num. Используйте эту форму, когда файловой системе нужен доступ для чтения внутри блока.

writeblocks(block_num: int, buf: bytes) → None

writeblocks(block_num: int, buf: bytes, offset: int) → None

Записывает байты из buf в устройство.

Простая форма (writeblocks(block_num, buf)): записывает целые блоки начиная с индекса блока block_num. len(buf) должно быть кратно размеру блока, а число записанных блоков равно len(buf) // block_size. Реализация отвечает за предварительное стирание каждого блока назначения, если этого требует базовое оборудование.

Расширенная форма (writeblocks(block_num, buf, offset)): записывает len(buf) байт — не обязательно целое число блоков — начиная с байтового смещения offset внутри блока block_num. Измениться могут только записываемые байты; вызывающая сторона отвечает за то, чтобы затрагиваемые блоки были стёрты предшествующим вызовом ioctl(6, block_num). Реализации этой формы никогда не должны неявно стирать блок, даже если offset равно нулю.

ioctl(op: int, arg: int) → int | None

Управляет блочным устройством и запрашивает его параметры. Выполняемая операция задаётся op, который является одним из следующих целых чисел:

• 1 — инициализировать устройство (arg не используется)

• 2 — выключить устройство (arg не используется)

• 3 — синхронизировать устройство (arg не используется)

• 4 — получить количество блоков, должно возвращать целое число (arg не используется)

• 5 — получить число байт в блоке, должно возвращать целое число либо None, в этом случае используется значение по умолчанию 512 (arg не используется)

• 6 — стереть блок, arg — номер стираемого блока

Как минимум должен перехватываться ioctl(4, ...); файловым системам, использующим расширенный интерфейс, дополнительно требуется ioctl(6, ...). Необходимость в остальных операциях зависит от оборудования.

Перед любым вызовом writeblocks(block, ...) файловая система, использующая расширенный интерфейс, выдаёт ioctl(6, block), чтобы драйвер мог предварительно стереть блок, если этого требует оборудование. Вместо этого драйвер может перехватывать ioctl(6, block) и возвращать 0 (успех), беря на себя ответственность за самостоятельное определение момента, когда нужно стирание.

Если не указано иное, ioctl(op, arg) может возвращать None. Следовательно, реализация может игнорировать неиспользуемые значения op. Там, где op перехватывается, возвращаемые значения для операций 4 и 5 описаны выше. Остальные операции должны возвращать 0 при успехе и ненулевое значение при сбое, причём возвращаемое значение является кодом ошибки errno OSError.