Split uos module into os and storage.

os is a subset of CPython's os. storage contains additional
file system mounting functionality based on UNIX's mount
management.

Fixes #140

5 files changed, 430 insertions, 7 deletions

diff --git a/shared-bindings/index.rst b/shared-bindings/index.rst
index e44c60f83..918fb5675 100644
--- a/shared-bindings/index.rst
+++ b/shared-bindings/index.rst
@@ -12,13 +12,13 @@ limited. For example, a microcontroller without analog features will not have
 Support Matrix
 ---------------
 
-===============  ==========  =========  ===========  =======  =======  ===========  =================  ================  =========  ========  =========  =======  =========
-Port             `analogio`  `audioio`  `bitbangio`  `board`  `busio`  `digitalio`  `microcontroller`  `neopixel_write`  `pulseio`  `time`    `touchio`  `uheap`  `usb_hid`
-===============  ==========  =========  ===========  =======  =======  ===========  =================  ================  =========  ========  =========  =======  =========
-SAMD21           **Yes**     No         No           **Yes**  **Yes**  **Yes**      **Yes**            **Yes**           No         **Yes**   **Yes**    Debug    **Yes**
-SAMD21 Express   **Yes**     **Yes**    **Yes**      **Yes**  **Yes**  **Yes**      **Yes**            **Yes**           **Yes**    **Yes**   **Yes**    Debug    **Yes**
-ESP8266          **Yes**     No         **Yes**      **Yes**  **Yes**  **Yes**      **Yes**            **Yes**           No         **Yes**   No         Debug    No
-===============  ==========  =========  ===========  =======  =======  ===========  =================  ================  =========  ========  =========  =======  =========
+===============  ==========  =========  ===========  =======  =======  ===========  =================  ================  =======  =========  =========  ========  =========  =======  =========
+Port             `analogio`  `audioio`  `bitbangio`  `board`  `busio`  `digitalio`  `microcontroller`  `neopixel_write`  `os`     `pulseio`  `storage`  `time`    `touchio`  `uheap`  `usb_hid`
+===============  ==========  =========  ===========  =======  =======  ===========  =================  ================  =======  =========  =========  ========  =========  =======  =========
+SAMD21           **Yes**     No         No           **Yes**  **Yes**  **Yes**      **Yes**            **Yes**           **Yes**  No         **Yes**    **Yes**   **Yes**    Debug    **Yes**
+SAMD21 Express   **Yes**     **Yes**    **Yes**      **Yes**  **Yes**  **Yes**      **Yes**            **Yes**           **Yes**  **Yes**    **Yes**    **Yes**   **Yes**    Debug    **Yes**
+ESP8266          **Yes**     No         **Yes**      **Yes**  **Yes**  **Yes**      **Yes**            **Yes**           **Yes**  No         **Yes**    **Yes**   No         Debug    No
+===============  ==========  =========  ===========  =======  =======  ===========  =================  ================  =======  =========  =========  ========  =========  =======  =========
 
 Modules
 ---------
diff --git a/shared-bindings/os/__init__.c b/shared-bindings/os/__init__.c
new file mode 100644
index 000000000..6185f0bf2
--- /dev/null
+++ b/shared-bindings/os/__init__.c
@@ -0,0 +1,221 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2013, 2014 Damien P. George
+ * Copyright (c) 2015 Josef Gajdusek
+ * Copyright (c) 2016 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include <string.h>
+
+#include "extmod/vfs.h"
+#include "lib/oofatfs/ff.h"
+#include "lib/oofatfs/diskio.h"
+#include "py/mpstate.h"
+#include "py/obj.h"
+#include "shared-bindings/os/__init__.h"
+
+//| :mod:`os` --- functions that an OS normally provides
+//| ========================================================
+//|
+//| .. module:: os
+//|   :synopsis: functions that an OS normally provides
+//|   :platform: SAMD21
+//|
+//| The `os` module is a strict subset of the CPython `cpython:os` module. So,
+//| code written in CircuitPython will work in CPython but not necessarily the
+//| other way around.
+//|
+
+//| .. function:: uname()
+//|
+//|   Returns a named tuple of operating specific and CircuitPython port
+//|   specific information.
+//|
+STATIC mp_obj_t os_uname(void) {
+    return common_hal_os_uname();
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_uname_obj, os_uname);
+
+//| .. function:: chdir(path)
+//|
+//|   Change current directory.
+//|
+mp_obj_t os_chdir(mp_obj_t path_in) {
+    const char *path = mp_obj_str_get_str(path_in);
+    common_hal_os_chdir(path);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_1(os_chdir_obj, os_chdir);
+
+//| .. function:: getcwd()
+//|
+//|   Get the current directory.
+//|
+mp_obj_t os_getcwd(void) {
+    return common_hal_os_getcwd();
+}
+MP_DEFINE_CONST_FUN_OBJ_0(os_getcwd_obj, os_getcwd);
+
+//| .. function:: listdir([dir])
+//|
+//|   With no argument, list the current directory.  Otherwise list the given directory.
+//|
+mp_obj_t os_listdir(size_t n_args, const mp_obj_t *args) {
+    const char* path;
+    if (n_args == 1) {
+        path = mp_obj_str_get_str(args[0]);
+    } else {
+        path = "";
+    }
+    return common_hal_os_listdir(path);
+}
+MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(os_listdir_obj, 0, 1, os_listdir);
+
+//| .. function:: mkdir(path)
+//|
+//|   Create a new directory.
+//|
+mp_obj_t os_mkdir(mp_obj_t path_in) {
+    const char *path = mp_obj_str_get_str(path_in);
+    common_hal_os_mkdir(path);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_1(os_mkdir_obj, os_mkdir);
+
+//| .. function:: remove(path)
+//|
+//|   Remove a file.
+//|
+mp_obj_t os_remove(mp_obj_t path_in) {
+    const char *path = mp_obj_str_get_str(path_in);
+    common_hal_os_remove(path);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_1(os_remove_obj, os_remove);
+
+//| .. function:: rmdir(path)
+//|
+//|   Remove a directory.
+//|
+mp_obj_t os_rename(mp_obj_t old_path_in, mp_obj_t new_path_in) {
+    const char *old_path = mp_obj_str_get_str(old_path_in);
+    const char *new_path = mp_obj_str_get_str(new_path_in);
+    common_hal_os_rename(old_path, new_path);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_2(os_rename_obj, os_rename);
+
+//| .. function:: rename(old_path, new_path)
+//|
+//|   Rename a file.
+//|
+mp_obj_t os_rmdir(mp_obj_t path_in) {
+    const char *path = mp_obj_str_get_str(path_in);
+    common_hal_os_rmdir(path);
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_1(os_rmdir_obj, os_rmdir);
+
+//| .. function:: stat(path)
+//|
+//|   Get the status of a file or directory.
+//|
+mp_obj_t os_stat(mp_obj_t path_in) {
+    const char *path = mp_obj_str_get_str(path_in);
+    return common_hal_os_stat(path);
+}
+MP_DEFINE_CONST_FUN_OBJ_1(os_stat_obj, os_stat);
+
+//| .. function:: statvfs(path)
+//|
+//|   Get the status of a fileystem.
+//|
+//|   Returns a tuple with the filesystem information in the following order:
+//|
+//|        * ``f_bsize`` -- file system block size
+//|        * ``f_frsize`` -- fragment size
+//|        * ``f_blocks`` -- size of fs in f_frsize units
+//|        * ``f_bfree`` -- number of free blocks
+//|        * ``f_bavail`` -- number of free blocks for unpriviliged users
+//|        * ``f_files`` -- number of inodes
+//|        * ``f_ffree`` -- number of free inodes
+//|        * ``f_favail`` -- number of free inodes for unpriviliged users
+//|        * ``f_flag`` -- mount flags
+//|        * ``f_namemax`` -- maximum filename length
+//|
+//|   Parameters related to inodes: ``f_files``, ``f_ffree``, ``f_avail``
+//|   and the ``f_flags`` parameter may return ``0`` as they can be unavailable
+//|   in a port-specific implementation.
+//|
+mp_obj_t os_statvfs(mp_obj_t path_in) {
+    const char *path = mp_obj_str_get_str(path_in);
+    return common_hal_os_statvfs(path);
+}
+MP_DEFINE_CONST_FUN_OBJ_1(os_statvfs_obj, os_statvfs);
+
+//| .. function:: sync()
+//|
+//|   Sync all filesystems.
+//|
+STATIC mp_obj_t os_sync(void) {
+    for (mp_vfs_mount_t *vfs = MP_STATE_VM(vfs_mount_table); vfs != NULL; vfs = vfs->next) {
+        // this assumes that vfs->obj is fs_user_mount_t with block device functions
+        disk_ioctl(MP_OBJ_TO_PTR(vfs->obj), CTRL_SYNC, NULL);
+    }
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync);
+
+
+STATIC const mp_rom_map_elem_t os_module_globals_table[] = {
+    { MP_OBJ_NEW_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_os) },
+
+    { MP_OBJ_NEW_QSTR(MP_QSTR_uname), MP_ROM_PTR(&os_uname_obj) },
+
+    { MP_OBJ_NEW_QSTR(MP_QSTR_chdir), MP_ROM_PTR(&os_chdir_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_getcwd), MP_ROM_PTR(&os_getcwd_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_listdir), MP_ROM_PTR(&os_listdir_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_mkdir), MP_ROM_PTR(&os_mkdir_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_remove), MP_ROM_PTR(&os_remove_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_rename), MP_ROM_PTR(&os_rename_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_rmdir), MP_ROM_PTR(&os_rmdir_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_stat), MP_ROM_PTR(&os_stat_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_statvfs), MP_ROM_PTR(&os_statvfs_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_unlink), MP_ROM_PTR(&os_remove_obj) }, // unlink aliases to remove
+
+    { MP_OBJ_NEW_QSTR(MP_QSTR_sync), MP_ROM_PTR(&os_sync_obj) },
+
+//| .. data:: sep
+//|
+//|   Separator used to dileneate path components such as folder and file names.
+//|
+    { MP_OBJ_NEW_QSTR(MP_QSTR_sep), MP_OBJ_NEW_QSTR(MP_QSTR__slash_) },
+};
+
+STATIC MP_DEFINE_CONST_DICT(os_module_globals, os_module_globals_table);
+
+const mp_obj_module_t os_module = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t*)&os_module_globals,
+};
diff --git a/shared-bindings/os/__init__.h b/shared-bindings/os/__init__.h
new file mode 100644
index 000000000..e04a39319
--- /dev/null
+++ b/shared-bindings/os/__init__.h
@@ -0,0 +1,48 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2016 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef __MICROPY_INCLUDED_SHARED_BINDINGS_OS___INIT___H__
+#define __MICROPY_INCLUDED_SHARED_BINDINGS_OS___INIT___H__
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#include "py/objtuple.h"
+
+const mp_rom_obj_tuple_t common_hal_os_uname_info_obj;
+
+mp_obj_t common_hal_os_uname(void);
+void common_hal_os_chdir(const char* path);
+mp_obj_t common_hal_os_getcwd(void);
+mp_obj_t common_hal_os_listdir(const char* path);
+void common_hal_os_mkdir(const char* path);
+void common_hal_os_remove(const char* path);
+void common_hal_os_rename(const char* old_path, const char* new_path);
+void common_hal_os_rmdir(const char* path);
+mp_obj_t common_hal_os_stat(const char* path);
+mp_obj_t common_hal_os_statvfs(const char* path);
+
+#endif  // __MICROPY_INCLUDED_SHARED_BINDINGS_OS___INIT___H__
diff --git a/shared-bindings/storage/__init__.c b/shared-bindings/storage/__init__.c
new file mode 100644
index 000000000..2b289a11f
--- /dev/null
+++ b/shared-bindings/storage/__init__.c
@@ -0,0 +1,117 @@
+/*
+ * This file is part of the Micro Python project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2013, 2014 Damien P. George
+ * Copyright (c) 2015 Josef Gajdusek
+ * Copyright (c) 2016 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include <string.h>
+
+#include "extmod/vfs_fat.h"
+#include "py/obj.h"
+#include "py/objnamedtuple.h"
+#include "shared-bindings/storage/__init__.h"
+
+//| :mod:`storage` --- storage management
+//| ========================================================
+//|
+//| .. module:: storage
+//|   :synopsis: storage management
+//|   :platform: SAMD21
+//|
+//| The `storage` provides storage management functionality such as mounting and
+//| unmounting which is typically handled by the operating system hosting Python.
+//| CircuitPython does not have an OS, so this module provides this functionality
+//| directly. Its based on MicroPython's `uos` module but deliberately separates
+//| CPython compatible functionality (in `os`) from incompatible functionality
+//| (in `storage`).
+//|
+
+//| .. function:: mount(filesystem, mount_path, \*, readonly=False)
+//|
+//|   Mounts the given filesystem object at the given path.
+//|
+//|   This is the CircuitPython analog to the UNIX ``mount`` command.
+//|
+mp_obj_t storage_mount(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    enum { ARG_readonly };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_readonly, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = mp_const_false} },
+    };
+
+    // parse args
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 2, pos_args + 2, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+
+    // get the mount point
+    const char *mnt_str = mp_obj_str_get_str(pos_args[1]);
+
+    // Make sure we're given an object we can mount.
+    // TODO(tannewt): Make sure we have all the methods we need to operating it
+    // as a file system.
+    mp_obj_t vfs_obj = pos_args[0];
+    mp_obj_t dest[2];
+    mp_load_method_maybe(vfs_obj, MP_QSTR_mount, dest);
+    if (dest[0] == MP_OBJ_NULL) {
+        mp_raise_ValueError("filesystem must provide mount method");
+    }
+
+    common_hal_storage_mount(vfs_obj, mnt_str, mp_obj_is_true(args[ARG_readonly].u_obj));
+
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_KW(storage_mount_obj, 2, storage_mount);
+
+//| .. function:: umount(mount)
+//|
+//|   Unmounts the given filesystem object or if *mount* is a path, then unmount
+//|   the filesystem mounted at that location.
+//|
+//|   This is the CircuitPython analog to the UNIX ``umount`` command.
+//|
+mp_obj_t storage_umount(mp_obj_t mnt_in) {
+    if (MP_OBJ_IS_STR(mnt_in)) {
+        common_hal_storage_umount_path(mp_obj_str_get_str(mnt_in));
+    } else {
+        common_hal_storage_umount_object(mnt_in);
+    }
+
+    return mp_const_none;
+}
+MP_DEFINE_CONST_FUN_OBJ_1(storage_umount_obj, storage_umount);
+
+STATIC const mp_rom_map_elem_t storage_module_globals_table[] = {
+    { MP_OBJ_NEW_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_storage) },
+
+    { MP_OBJ_NEW_QSTR(MP_QSTR_mount), MP_ROM_PTR(&storage_mount_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_umount), MP_ROM_PTR(&storage_umount_obj) },
+    { MP_OBJ_NEW_QSTR(MP_QSTR_VfsFat), MP_ROM_PTR(&mp_fat_vfs_type) },
+};
+
+STATIC MP_DEFINE_CONST_DICT(storage_module_globals, storage_module_globals_table);
+
+const mp_obj_module_t storage_module = {
+    .base = { &mp_type_module },
+    .globals = (mp_obj_dict_t*)&storage_module_globals,
+};
diff --git a/shared-bindings/storage/__init__.h b/shared-bindings/storage/__init__.h
new file mode 100644
index 000000000..806bbc8b3
--- /dev/null
+++ b/shared-bindings/storage/__init__.h
@@ -0,0 +1,37 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2017 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef __MICROPY_INCLUDED_SHARED_BINDINGS_STORAGE___INIT___H__
+#define __MICROPY_INCLUDED_SHARED_BINDINGS_STORAGE___INIT___H__
+
+#include <stdint.h>
+#include <stdbool.h>
+
+void common_hal_storage_mount(mp_obj_t vfs_obj, const char* path, bool readonly);
+void common_hal_storage_umount_path(const char* path);
+void common_hal_storage_umount_object(mp_obj_t vfs_obj);
+
+#endif  // __MICROPY_INCLUDED_SHARED_BINDINGS_STORAGE___INIT___H__