Add Block Device Support

BUILD.bazel

@@ -145,6 +145,8 @@ cc_binary(
         "//errors",
         "//lib/nlohmann_json:json",
         "//picoboot_connection",
+        "//lib/littlefs",
+        "//lib/oofatfs:fatfs",
         "@libusb",
         "@pico-sdk//src/common/boot_picobin_headers",
         "@pico-sdk//src/common/boot_picoboot_headers",

CMakeLists.txt

@@ -340,6 +340,8 @@ else()
     target_compile_definitions(picotool PRIVATE HAS_LIBUSB=1)
     target_link_libraries(picotool 
         picoboot_connection_cxx
+        fatfs
+        littlefs
         ${LIBUSB_LIBRARIES})
 endif()
 

README.md

@@ -12,6 +12,7 @@ PICOTOOL:
 SYNOPSIS:
     picotool info [-b] [-m] [-p] [-d] [--debug] [-l] [-a] [device-selection]
     picotool info [-b] [-m] [-p] [-d] [--debug] [-l] [-a] <filename> [-t <type>]
+    picotool bdev ls|mkdir|cp|rm|cat
     picotool config [-s <key> <value>] [-g <group>] [device-selection]
     picotool config [-s <key> <value>] [-g <group>] <filename> [-t <type>]
     picotool load [--ignore-partitions] [--family <family_id>] [-p <partition>] [-n] [-N] [-u] [-v] [-x] <filename> [-t <type>] [-o
@@ -39,6 +40,7 @@ SYNOPSIS:
 COMMANDS:
     info        Display information from the target device(s) or file.
                 Without any arguments, this will display basic information for all connected RP-series devices in BOOTSEL mode
+    bdev        Commands related to embedded block devices
     config      Display or change program configuration settings from the target device(s) or file.
     load        Load the program / memory range stored in a file onto the device.
     encrypt     Encrypt the program.
@@ -1392,6 +1394,266 @@ OPTIONS:
             The file name
 ```
 
+## bdev
+
+The `bdev` commands are for interacting with block devices in Flash. These can either be defined using binary info, or you can specify a partition to use as a block device. They work with a LittleFS filesystem, or a FatFS filesystem.
+
+```text
+$ picotool help bdev
+BDEV:
+    Commands related to embedded block devices
+
+SYNOPSIS:
+    picotool bdev ls <dirname> [-r] [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+    picotool bdev mkdir <dirname> [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+    picotool bdev cp <src> <dest> [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+    picotool bdev rm <filename> [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+    picotool bdev cat <filename> [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+
+SUB COMMANDS:
+    ls      List contents of the block device
+    mkdir   Create directory on the block device
+    cp      Copy file to/from the block device - use :filename to indicate files on the device (eg `cp main.py :main.py` to upload to the
+            device)
+    rm      Delete a file or an empty directory on the block device
+    cat     Print contents of file on the block device
+```
+
+### ls
+
+List contents of the block device
+
+```text
+$ picotool help bdev ls
+BDEV LS:
+    List contents of the block device
+
+SYNOPSIS:
+    picotool bdev ls <dirname> [-r] [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+
+OPTIONS:
+        <dirname>
+            The directory name to list (optional)
+        -r, --recursive
+            List files in directories recursively
+    Block device options
+        -p, --partition
+            Partition to use as block device
+        <partition>
+            partition number
+        --filesystem
+            Specify filesystem to use
+        <fs>
+            littlefs|fatfs
+        --format
+            Format the drive if necessary (may result in data loss)
+    Target device selection
+        --bus <bus>
+            Filter devices by USB bus number
+        --address <addr>
+            Filter devices by USB device address
+        --vid <vid>
+            Filter by vendor id
+        --pid <pid>
+            Filter by product id
+        --ser <ser>
+            Filter by serial number
+        -f, --force
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be rebooted back to application mode
+        -F, --force-no-reboot
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be left connected and accessible to picotool, but without the
+            USB drive mounted
+```
+
+### mkdir
+
+Create directory on the block device
+
+```text
+$ picotool help bdev mkdir
+BDEV MKDIR:
+    Create directory on the block device
+
+SYNOPSIS:
+    picotool bdev mkdir <dirname> [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+
+OPTIONS:
+        <dirname>
+            The directory name
+    Block device options
+        -p, --partition
+            Partition to use as block device
+        <partition>
+            partition number
+        --filesystem
+            Specify filesystem to use
+        <fs>
+            littlefs|fatfs
+        --format
+            Format the drive if necessary (may result in data loss)
+    Target device selection
+        --bus <bus>
+            Filter devices by USB bus number
+        --address <addr>
+            Filter devices by USB device address
+        --vid <vid>
+            Filter by vendor id
+        --pid <pid>
+            Filter by product id
+        --ser <ser>
+            Filter by serial number
+        -f, --force
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be rebooted back to application mode
+        -F, --force-no-reboot
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be left connected and accessible to picotool, but without the
+            USB drive mounted
+```
+
+### cp
+
+Copy file to/from the block device - use :filename to indicate files on the device (e.g. `cp main.py :main.py` to upload to the device, or `cp :main.py main.py` to download from the device)  
+
+
+```text
+$ picotool help bdev cp
+BDEV CP:
+    Copy file to/from the block device - use :filename to indicate files on the device (eg `cp main.py :main.py` to upload to the device)
+
+SYNOPSIS:
+    picotool bdev cp <src> <dest> [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+
+OPTIONS:
+        <src>
+            The file name
+        <dest>
+            The file name
+    Block device options
+        -p, --partition
+            Partition to use as block device
+        <partition>
+            partition number
+        --filesystem
+            Specify filesystem to use
+        <fs>
+            littlefs|fatfs
+        --format
+            Format the drive if necessary (may result in data loss)
+    Target device selection
+        --bus <bus>
+            Filter devices by USB bus number
+        --address <addr>
+            Filter devices by USB device address
+        --vid <vid>
+            Filter by vendor id
+        --pid <pid>
+            Filter by product id
+        --ser <ser>
+            Filter by serial number
+        -f, --force
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be rebooted back to application mode
+        -F, --force-no-reboot
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be left connected and accessible to picotool, but without the
+            USB drive mounted
+```
+
+### rm
+
+Delete a file or an empty directory on the block device
+
+```text
+$ picotool help bdev rm
+BDEV RM:
+    Delete a file or an empty directory on the block device
+
+SYNOPSIS:
+    picotool bdev rm <filename> [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+
+OPTIONS:
+        <filename>
+            The file name
+    Block device options
+        -p, --partition
+            Partition to use as block device
+        <partition>
+            partition number
+        --filesystem
+            Specify filesystem to use
+        <fs>
+            littlefs|fatfs
+        --format
+            Format the drive if necessary (may result in data loss)
+    Target device selection
+        --bus <bus>
+            Filter devices by USB bus number
+        --address <addr>
+            Filter devices by USB device address
+        --vid <vid>
+            Filter by vendor id
+        --pid <pid>
+            Filter by product id
+        --ser <ser>
+            Filter by serial number
+        -f, --force
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be rebooted back to application mode
+        -F, --force-no-reboot
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be left connected and accessible to picotool, but without the
+            USB drive mounted
+```
+
+### cat
+
+Print contents of file on the block device
+
+```text
+$ picotool help bdev cat
+BDEV CAT:
+    Print contents of file on the block device
+
+SYNOPSIS:
+    picotool bdev cat <filename> [-p <partition>] [--filesystem <fs>] [--format] [device-selection]
+
+OPTIONS:
+        <filename>
+            The file name
+    Block device options
+        -p, --partition
+            Partition to use as block device
+        <partition>
+            partition number
+        --filesystem
+            Specify filesystem to use
+        <fs>
+            littlefs|fatfs
+        --format
+            Format the drive if necessary (may result in data loss)
+    Target device selection
+        --bus <bus>
+            Filter devices by USB bus number
+        --address <addr>
+            Filter devices by USB device address
+        --vid <vid>
+            Filter by vendor id
+        --pid <pid>
+            Filter by product id
+        --ser <ser>
+            Filter by serial number
+        -f, --force
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be rebooted back to application mode
+        -F, --force-no-reboot
+            Force a device not in BOOTSEL mode but running compatible code to reset so the command can be executed. After executing the
+            command (unless the command itself is a 'reboot') the device will be left connected and accessible to picotool, but without the
+            USB drive mounted
+```
+
 ## Binary Information
 
 Binary information is machine locatable and generally machine consumable. I say generally because anyone can

lib/CMakeLists.txt

@@ -18,6 +18,9 @@ endif()
 set(JSON_BuildTests OFF CACHE INTERNAL "")
 add_subdirectory(nlohmann_json EXCLUDE_FROM_ALL)
 
+add_subdirectory(oofatfs EXCLUDE_FROM_ALL)
+add_subdirectory(littlefs EXCLUDE_FROM_ALL)
+
 add_subdirectory(whereami EXCLUDE_FROM_ALL)
 
 # Taken from pico-sdk/src/rp2_common/pico_mbedtls/CMakeLists.txt

lib/littlefs/BUILD.bazel

@@ -0,0 +1,14 @@
+package(default_visibility = ["//visibility:public"])
+
+cc_library(
+    name = "littlefs",
+    srcs = [
+        "lfs.c",
+        "lfs_util.c",
+    ],
+    hdrs = [
+        "lfs.h",
+        "lfs_util.h",
+    ],
+    includes = ["."],
+)

lib/littlefs/CMakeLists.txt

@@ -0,0 +1,9 @@
+add_library(littlefs INTERFACE)
+
+target_sources(littlefs INTERFACE
+        ${CMAKE_CURRENT_LIST_DIR}/lfs.c
+        ${CMAKE_CURRENT_LIST_DIR}/lfs_util.c)
+
+target_include_directories(littlefs INTERFACE ${CMAKE_CURRENT_LIST_DIR})
+
+target_compile_definitions(littlefs INTERFACE LFS_NO_ERROR=1)

lib/littlefs/LICENSE.md

@@ -0,0 +1,25 @@
+Copyright (c) 2022, The littlefs authors.  
+Copyright (c) 2017, Arm Limited. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+-  Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+-  Redistributions in binary form must reproduce the above copyright notice, this
+   list of conditions and the following disclaimer in the documentation and/or
+   other materials provided with the distribution.
+-  Neither the name of ARM nor the names of its contributors may be used to
+   endorse or promote products derived from this software without specific prior
+   written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

lib/littlefs/README.md

@@ -0,0 +1,7 @@
+littlefs library
+================
+
+The upstream source for the files in this directory is
+https://github.com/littlefs-project/littlefs
+
+The current files come from v2.11.1