From c0679ea855172dea94aeefdd22648f728e489c9f Mon Sep 17 00:00:00 2001 From: Isaac Benitez Date: Sun, 19 Mar 2023 14:11:40 -0700 Subject: [PATCH 1/5] Define BlockDevice class for VfsFat block device arguments --- circuitpython_typing/__init__.py | 53 ++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/circuitpython_typing/__init__.py b/circuitpython_typing/__init__.py index 5a56cec..c0e0d9d 100644 --- a/circuitpython_typing/__init__.py +++ b/circuitpython_typing/__init__.py @@ -24,6 +24,7 @@ __all__ = [ "Alarm", "AudioSample", + "BlockDevice", "ByteStream", "FrameBuffer", "ReadableBuffer", @@ -72,6 +73,58 @@ def write(self, buf: ReadableBuffer) -> Optional[int]: """Write the bytes in ``buf`` to the stream.""" +class BlockDevice(Protocol): + """Protocol for block device objects to enable a device to support + CircuitPython filesystems. Classes which implement this protocol + include `storage.VfsFat`. + """ + + def readblocks(self, block_num: int, buf: bytearray) -> None: + """Read aligned, multiples of blocks. Starting at + the block given by the index ``block_num``, read blocks + from the device into ``buf`` (an array of bytes). The number + of blocks to read is given by the length of ``buf``, + which will be a multiple of the block size. + """ + + def writeblocks(self, block_num: int, buf: bytearray) -> None: + """Write aligned, multiples of blocks, and require that + the blocks that are written to be first erased (if necessary) + by this method. Starting at the block given by the index + ``block_num``, write blocks from ``buf`` (an array of bytes) to the + device. The number of blocks to write is given by the length + of ``buf``, which will be a multiple of the block size. + """ + + def ioctl(self, operation: int, arg: Optional[int] = None) -> Optional[int]: + """Control the block device and query its parameters. The operation to + perform is given by ``operation`` which is one of the following integers: + + * 1 - initialise the device (``arg`` is unused) + * 2 - shutdown the device (``arg`` is unused) + * 3 - sync the device (``arg`` is unused) + * 4 - get a count of the number of blocks, should return an integer (``arg`` is unused) + * 5 - get the number of bytes in a block, should return an integer, + or ``None`` in which case the default value of 512 is used (``arg`` is unused) + * 6 - erase a block, arg is the block number to erase + + As a minimum ``ioctl(4, ...)`` must be intercepted; for littlefs ``ioctl(6, ...)`` + must also be intercepted. The need for others is hardware dependent. + + Prior to any call to ``writeblocks(block, ...)`` littlefs issues ``ioctl(6, block)``. + This enables a device driver to erase the block prior to a write if the hardware + requires it. Alternatively a driver might intercept ``ioctl(6, block)`` and return 0 + (success). In this case the driver assumes responsibility for detecting the need + for erasure. + + Unless otherwise stated ``ioctl(operation, arg)`` can return ``None``. Consequently an + implementation can ignore unused values of ``operation``. Where ``operation`` is + intercepted, the return value for operations 4 and 5 are as detailed above. Other + operations should return 0 on success and non-zero for failure, with the value returned + being an ``OSError`` errno code. + """ + + # These types may not be in adafruit-blinka, so use the string form instead of a resolved name. AudioSample: TypeAlias = Union[ From 7f3a04c249e4ccd038c65d19d9e5e1eb9d1b02ed Mon Sep 17 00:00:00 2001 From: Isaac Benitez Date: Sun, 19 Mar 2023 14:32:30 -0700 Subject: [PATCH 2/5] Fix Bullet list ends without a blank line error --- circuitpython_typing/__init__.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/circuitpython_typing/__init__.py b/circuitpython_typing/__init__.py index c0e0d9d..b251057 100644 --- a/circuitpython_typing/__init__.py +++ b/circuitpython_typing/__init__.py @@ -53,11 +53,13 @@ class ByteStream(Protocol): """Protocol for basic I/O operations on a byte stream. - Classes which implement this protocol include + Classes which implement this protocol include: + * `io.BytesIO` * `io.FileIO` (for a file open in binary mode) * `busio.UART` * `usb_cdc.Serial` + """ # Should be `, /)`, but not available in Python 3.7. From a458701fd75d19b5105607ec52c26af5c42c92a1 Mon Sep 17 00:00:00 2001 From: Isaac Benitez Date: Sun, 19 Mar 2023 14:40:24 -0700 Subject: [PATCH 3/5] Fix Bullet list ends without a blank line error --- circuitpython_typing/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/circuitpython_typing/__init__.py b/circuitpython_typing/__init__.py index b251057..05d28ad 100644 --- a/circuitpython_typing/__init__.py +++ b/circuitpython_typing/__init__.py @@ -9,6 +9,7 @@ * Author(s): Alec Delaney, Dan Halbert, Randy Hudson + """ __version__ = "0.0.0+auto.0" From f8ec09ed6182f08a6a31934824ce9403b8d55c39 Mon Sep 17 00:00:00 2001 From: Isaac Benitez Date: Sun, 19 Mar 2023 14:49:14 -0700 Subject: [PATCH 4/5] Fix Bullet list ends without a blank line error --- circuitpython_typing/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/circuitpython_typing/__init__.py b/circuitpython_typing/__init__.py index 05d28ad..169a0ba 100644 --- a/circuitpython_typing/__init__.py +++ b/circuitpython_typing/__init__.py @@ -108,7 +108,7 @@ def ioctl(self, operation: int, arg: Optional[int] = None) -> Optional[int]: * 3 - sync the device (``arg`` is unused) * 4 - get a count of the number of blocks, should return an integer (``arg`` is unused) * 5 - get the number of bytes in a block, should return an integer, - or ``None`` in which case the default value of 512 is used (``arg`` is unused) + or ``None`` in which case the default value of 512 is used (``arg`` is unused) * 6 - erase a block, arg is the block number to erase As a minimum ``ioctl(4, ...)`` must be intercepted; for littlefs ``ioctl(6, ...)`` From e7bf93eaf15e9fcce3cd9aaf6a2caf6f3fc76d24 Mon Sep 17 00:00:00 2001 From: Isaac Benitez Date: Sun, 19 Mar 2023 14:54:45 -0700 Subject: [PATCH 5/5] Undo unnecessary added blank lines --- circuitpython_typing/__init__.py | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/circuitpython_typing/__init__.py b/circuitpython_typing/__init__.py index 169a0ba..a826ae2 100644 --- a/circuitpython_typing/__init__.py +++ b/circuitpython_typing/__init__.py @@ -9,7 +9,6 @@ * Author(s): Alec Delaney, Dan Halbert, Randy Hudson - """ __version__ = "0.0.0+auto.0" @@ -54,13 +53,11 @@ class ByteStream(Protocol): """Protocol for basic I/O operations on a byte stream. - Classes which implement this protocol include: - + Classes which implement this protocol include * `io.BytesIO` * `io.FileIO` (for a file open in binary mode) * `busio.UART` * `usb_cdc.Serial` - """ # Should be `, /)`, but not available in Python 3.7.