@@ -136,192 +136,30 @@ Terminal redirection and duplication
136136Filesystem mounting
137137-------------------
138138
139- Some ports provide a Virtual Filesystem (VFS) and the ability to mount multiple
140- "real" filesystems within this VFS. Filesystem objects can be mounted at either
141- the root of the VFS, or at a subdirectory that lives in the root. This allows
142- dynamic and flexible configuration of the filesystem that is seen by Python
143- programs. Ports that have this functionality provide the :func: `mount ` and
144- :func: `umount ` functions, and possibly various filesystem implementations
145- represented by VFS classes.
139+ The following functions and classes have been moved to the :mod: `vfs ` module.
140+ They are provided in this module only for backwards compatibility and will be
141+ removed in version 2 of MicroPython.
146142
147143.. function :: mount(fsobj, mount_point, *, readonly)
148144
149- Mount the filesystem object *fsobj * at the location in the VFS given by the
150- *mount_point * string. *fsobj * can be a a VFS object that has a ``mount() ``
151- method, or a block device. If it's a block device then the filesystem type
152- is automatically detected (an exception is raised if no filesystem was
153- recognised). *mount_point * may be ``'/' `` to mount *fsobj * at the root,
154- or ``'/<name>' `` to mount it at a subdirectory under the root.
155-
156- If *readonly * is ``True `` then the filesystem is mounted read-only.
157-
158- During the mount process the method ``mount() `` is called on the filesystem
159- object.
160-
161- Will raise ``OSError(EPERM) `` if *mount_point * is already mounted.
145+ See `vfs.mount `.
162146
163147.. function :: umount(mount_point)
164148
165- Unmount a filesystem. *mount_point * can be a string naming the mount location,
166- or a previously-mounted filesystem object. During the unmount process the
167- method ``umount() `` is called on the filesystem object.
168-
169- Will raise ``OSError(EINVAL) `` if *mount_point * is not found.
149+ See `vfs.umount `.
170150
171151.. class :: VfsFat(block_dev)
172152
173- Create a filesystem object that uses the FAT filesystem format. Storage of
174- the FAT filesystem is provided by *block_dev *.
175- Objects created by this constructor can be mounted using :func: `mount `.
176-
177- .. staticmethod :: mkfs(block_dev)
178-
179- Build a FAT filesystem on *block_dev *.
153+ See `vfs.VfsFat `.
180154
181155.. class :: VfsLfs1(block_dev, readsize=32, progsize=32, lookahead=32)
182156
183- Create a filesystem object that uses the `littlefs v1 filesystem format `_.
184- Storage of the littlefs filesystem is provided by *block_dev *, which must
185- support the :ref: `extended interface <block-device-interface >`.
186- Objects created by this constructor can be mounted using :func: `mount `.
187-
188- See :ref: `filesystem ` for more information.
189-
190- .. staticmethod :: mkfs(block_dev, readsize=32, progsize=32, lookahead=32)
191-
192- Build a Lfs1 filesystem on *block_dev *.
193-
194- .. note :: There are reports of littlefs v1 failing in certain situations,
195- for details see `littlefs issue 347 `_.
157+ See `vfs.VfsLfs1 `.
196158
197159.. class :: VfsLfs2(block_dev, readsize=32, progsize=32, lookahead=32, mtime=True)
198160
199- Create a filesystem object that uses the `littlefs v2 filesystem format `_.
200- Storage of the littlefs filesystem is provided by *block_dev *, which must
201- support the :ref: `extended interface <block-device-interface >`.
202- Objects created by this constructor can be mounted using :func: `mount `.
161+ See `vfs.VfsLfs2 `.
162+
163+ .. class :: VfsPosix(root=None)
203164
204- The *mtime * argument enables modification timestamps for files, stored using
205- littlefs attributes. This option can be disabled or enabled differently each
206- mount time and timestamps will only be added or updated if *mtime * is enabled,
207- otherwise the timestamps will remain untouched. Littlefs v2 filesystems without
208- timestamps will work without reformatting and timestamps will be added
209- transparently to existing files once they are opened for writing. When *mtime *
210- is enabled `os.stat ` on files without timestamps will return 0 for the timestamp.
211-
212- See :ref: `filesystem ` for more information.
213-
214- .. staticmethod :: mkfs(block_dev, readsize=32, progsize=32, lookahead=32)
215-
216- Build a Lfs2 filesystem on *block_dev *.
217-
218- .. note :: There are reports of littlefs v2 failing in certain situations,
219- for details see `littlefs issue 295 `_.
220-
221- .. _littlefs v1 filesystem format : https://github.com/ARMmbed/littlefs/tree/v1
222- .. _littlefs v2 filesystem format : https://github.com/ARMmbed/littlefs
223- .. _littlefs issue 295 : https://github.com/ARMmbed/littlefs/issues/295
224- .. _littlefs issue 347 : https://github.com/ARMmbed/littlefs/issues/347
225-
226- Block devices
227- -------------
228-
229- A block device is an object which implements the block protocol. This enables a
230- device to support MicroPython filesystems. The physical hardware is represented
231- by a user defined class. The :class: `AbstractBlockDev ` class is a template for
232- the design of such a class: MicroPython does not actually provide that class,
233- but an actual block device class must implement the methods described below.
234-
235- A concrete implementation of this class will usually allow access to the
236- memory-like functionality of a piece of hardware (like flash memory). A block
237- device can be formatted to any supported filesystem and mounted using ``os ``
238- methods.
239-
240- See :ref: `filesystem ` for example implementations of block devices using the
241- two variants of the block protocol described below.
242-
243- .. _block-device-interface :
244-
245- Simple and extended interface
246- .............................
247-
248- There are two compatible signatures for the ``readblocks `` and ``writeblocks ``
249- methods (see below), in order to support a variety of use cases. A given block
250- device may implement one form or the other, or both at the same time. The second
251- form (with the offset parameter) is referred to as the "extended interface".
252-
253- Some filesystems (such as littlefs) that require more control over write
254- operations, for example writing to sub-block regions without erasing, may require
255- that the block device supports the extended interface.
256-
257- .. class :: AbstractBlockDev(...)
258-
259- Construct a block device object. The parameters to the constructor are
260- dependent on the specific block device.
261-
262- .. method :: readblocks(block_num, buf)
263- readblocks(block_num, buf, offset)
264-
265- The first form reads aligned, multiples of blocks.
266- Starting at the block given by the index *block_num *, read blocks from
267- the device into *buf * (an array of bytes).
268- The number of blocks to read is given by the length of *buf *,
269- which will be a multiple of the block size.
270-
271- The second form allows reading at arbitrary locations within a block,
272- and arbitrary lengths.
273- Starting at block index *block_num *, and byte offset within that block
274- of *offset *, read bytes from the device into *buf * (an array of bytes).
275- The number of bytes to read is given by the length of *buf *.
276-
277- .. method :: writeblocks(block_num, buf)
278- writeblocks(block_num, buf, offset)
279-
280- The first form writes aligned, multiples of blocks, and requires that the
281- blocks that are written to be first erased (if necessary) by this method.
282- Starting at the block given by the index *block_num *, write blocks from
283- *buf * (an array of bytes) to the device.
284- The number of blocks to write is given by the length of *buf *,
285- which will be a multiple of the block size.
286-
287- The second form allows writing at arbitrary locations within a block,
288- and arbitrary lengths. Only the bytes being written should be changed,
289- and the caller of this method must ensure that the relevant blocks are
290- erased via a prior ``ioctl `` call.
291- Starting at block index *block_num *, and byte offset within that block
292- of *offset *, write bytes from *buf * (an array of bytes) to the device.
293- The number of bytes to write is given by the length of *buf *.
294-
295- Note that implementations must never implicitly erase blocks if the offset
296- argument is specified, even if it is zero.
297-
298- .. method :: ioctl(op, arg)
299-
300- Control the block device and query its parameters. The operation to
301- perform is given by *op * which is one of the following integers:
302-
303- - 1 -- initialise the device (*arg * is unused)
304- - 2 -- shutdown the device (*arg * is unused)
305- - 3 -- sync the device (*arg * is unused)
306- - 4 -- get a count of the number of blocks, should return an integer
307- (*arg * is unused)
308- - 5 -- get the number of bytes in a block, should return an integer,
309- or ``None `` in which case the default value of 512 is used
310- (*arg * is unused)
311- - 6 -- erase a block, *arg * is the block number to erase
312-
313- As a minimum ``ioctl(4, ...) `` must be intercepted; for littlefs
314- ``ioctl(6, ...) `` must also be intercepted. The need for others is
315- hardware dependent.
316-
317- Prior to any call to ``writeblocks(block, ...) `` littlefs issues
318- ``ioctl(6, block) ``. This enables a device driver to erase the block
319- prior to a write if the hardware requires it. Alternatively a driver
320- might intercept ``ioctl(6, block) `` and return 0 (success). In this case
321- the driver assumes responsibility for detecting the need for erasure.
322-
323- Unless otherwise stated ``ioctl(op, arg) `` can return ``None ``.
324- Consequently an implementation can ignore unused values of ``op ``. Where
325- ``op `` is intercepted, the return value for operations 4 and 5 are as
326- detailed above. Other operations should return 0 on success and non-zero
327- for failure, with the value returned being an ``OSError `` errno code.
165+ See `vfs.VfsPosix `.
0 commit comments