Commit ea439e59 authored by Damien George's avatar Damien George
Browse files

stmhal: Start of documentation for modos and modtime.

parent ef7a066c
...@@ -41,6 +41,19 @@ ...@@ -41,6 +41,19 @@
#include "sdcard.h" #include "sdcard.h"
#include "portmodules.h" #include "portmodules.h"
/// \module os - basic "operating system" services
///
/// The `os` module contains functions for filesystem access and `urandom`.
///
/// The filesystem has `/` as the root directory, and the available physical
/// drives are accessible from here. They are currently:
///
/// /flash -- the internal flash filesystem
/// /sd -- the SD card (if it exists)
///
/// On boot up, the current directory is `/flash` if no SD card is inserted,
/// otherwise it is `/sd`.
#if _USE_LFN #if _USE_LFN
static char lfn[_MAX_LFN + 1]; /* Buffer to store the LFN */ static char lfn[_MAX_LFN + 1]; /* Buffer to store the LFN */
#endif #endif
...@@ -54,6 +67,8 @@ STATIC bool sd_in_root(void) { ...@@ -54,6 +67,8 @@ STATIC bool sd_in_root(void) {
#endif #endif
} }
/// \function chdir(path)
/// Change current directory.
STATIC mp_obj_t os_chdir(mp_obj_t path_in) { STATIC mp_obj_t os_chdir(mp_obj_t path_in) {
const char *path; const char *path;
path = mp_obj_str_get_str(path_in); path = mp_obj_str_get_str(path_in);
...@@ -73,6 +88,8 @@ STATIC mp_obj_t os_chdir(mp_obj_t path_in) { ...@@ -73,6 +88,8 @@ STATIC mp_obj_t os_chdir(mp_obj_t path_in) {
} }
STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_chdir_obj, os_chdir); STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_chdir_obj, os_chdir);
/// \function getcwd()
/// Get the current directory.
STATIC mp_obj_t os_getcwd(void) { STATIC mp_obj_t os_getcwd(void) {
char buf[MICROPY_ALLOC_PATH_MAX + 1]; char buf[MICROPY_ALLOC_PATH_MAX + 1];
FRESULT res = f_getcwd(buf, sizeof buf); FRESULT res = f_getcwd(buf, sizeof buf);
...@@ -85,6 +102,8 @@ STATIC mp_obj_t os_getcwd(void) { ...@@ -85,6 +102,8 @@ STATIC mp_obj_t os_getcwd(void) {
} }
STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_getcwd_obj, os_getcwd); STATIC 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.
STATIC mp_obj_t os_listdir(uint n_args, const mp_obj_t *args) { STATIC mp_obj_t os_listdir(uint n_args, const mp_obj_t *args) {
bool is_str_type = true; bool is_str_type = true;
const char *path; const char *path;
...@@ -161,6 +180,8 @@ STATIC mp_obj_t os_listdir(uint n_args, const mp_obj_t *args) { ...@@ -161,6 +180,8 @@ STATIC mp_obj_t os_listdir(uint n_args, const mp_obj_t *args) {
} }
STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(os_listdir_obj, 0, 1, os_listdir); STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(os_listdir_obj, 0, 1, os_listdir);
/// \function mkdir(path)
/// Create a new directory.
STATIC mp_obj_t os_mkdir(mp_obj_t path_o) { STATIC mp_obj_t os_mkdir(mp_obj_t path_o) {
const char *path = mp_obj_str_get_str(path_o); const char *path = mp_obj_str_get_str(path_o);
FRESULT res = f_mkdir(path); FRESULT res = f_mkdir(path);
...@@ -176,6 +197,8 @@ STATIC mp_obj_t os_mkdir(mp_obj_t path_o) { ...@@ -176,6 +197,8 @@ STATIC mp_obj_t os_mkdir(mp_obj_t path_o) {
} }
STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_mkdir_obj, os_mkdir); STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_mkdir_obj, os_mkdir);
/// \function remove(path)
/// Remove a file.
STATIC mp_obj_t os_remove(mp_obj_t path_o) { STATIC mp_obj_t os_remove(mp_obj_t path_o) {
const char *path = mp_obj_str_get_str(path_o); const char *path = mp_obj_str_get_str(path_o);
// TODO check that path is actually a file before trying to unlink it // TODO check that path is actually a file before trying to unlink it
...@@ -189,6 +212,8 @@ STATIC mp_obj_t os_remove(mp_obj_t path_o) { ...@@ -189,6 +212,8 @@ STATIC mp_obj_t os_remove(mp_obj_t path_o) {
} }
STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_remove_obj, os_remove); STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_remove_obj, os_remove);
/// \function rmdir(path)
/// Remove a directory.
STATIC mp_obj_t os_rmdir(mp_obj_t path_o) { STATIC mp_obj_t os_rmdir(mp_obj_t path_o) {
const char *path = mp_obj_str_get_str(path_o); const char *path = mp_obj_str_get_str(path_o);
// TODO check that path is actually a directory before trying to unlink it // TODO check that path is actually a directory before trying to unlink it
...@@ -217,6 +242,8 @@ STATIC bool path_equal(const char *path, const char *path_canonical) { ...@@ -217,6 +242,8 @@ STATIC bool path_equal(const char *path, const char *path_canonical) {
return *path == '\0'; return *path == '\0';
} }
/// \function stat(path)
/// Get the status of a file or directory.
STATIC mp_obj_t os_stat(mp_obj_t path_in) { STATIC mp_obj_t os_stat(mp_obj_t path_in) {
const char *path = mp_obj_str_get_str(path_in); const char *path = mp_obj_str_get_str(path_in);
...@@ -278,6 +305,8 @@ error: ...@@ -278,6 +305,8 @@ error:
} }
STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_stat_obj, os_stat); STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_stat_obj, os_stat);
/// \function sync()
/// Sync all filesystems.
STATIC mp_obj_t os_sync(void) { STATIC mp_obj_t os_sync(void) {
storage_flush(); storage_flush();
return mp_const_none; return mp_const_none;
...@@ -285,6 +314,9 @@ STATIC mp_obj_t os_sync(void) { ...@@ -285,6 +314,9 @@ STATIC mp_obj_t os_sync(void) {
STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync); STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync);
#if MICROPY_HW_ENABLE_RNG #if MICROPY_HW_ENABLE_RNG
/// \function urandom(n)
/// Return a bytes object with n random bytes, generated by the hardware
/// random number generator.
STATIC mp_obj_t os_urandom(mp_obj_t num) { STATIC mp_obj_t os_urandom(mp_obj_t num) {
mp_int_t n = mp_obj_get_int(num); mp_int_t n = mp_obj_get_int(num);
byte *data; byte *data;
...@@ -311,6 +343,7 @@ STATIC const mp_map_elem_t os_module_globals_table[] = { ...@@ -311,6 +343,7 @@ STATIC const mp_map_elem_t os_module_globals_table[] = {
{ MP_OBJ_NEW_QSTR(MP_QSTR_sync), (mp_obj_t)&os_sync_obj }, { MP_OBJ_NEW_QSTR(MP_QSTR_sync), (mp_obj_t)&os_sync_obj },
/// \constant sep - separation character used in paths
{ MP_OBJ_NEW_QSTR(MP_QSTR_sep), MP_OBJ_NEW_QSTR(MP_QSTR__slash_) }, { MP_OBJ_NEW_QSTR(MP_QSTR_sep), MP_OBJ_NEW_QSTR(MP_QSTR__slash_) },
#if MICROPY_HW_ENABLE_RNG #if MICROPY_HW_ENABLE_RNG
......
...@@ -34,6 +34,11 @@ ...@@ -34,6 +34,11 @@
#include "portmodules.h" #include "portmodules.h"
#include "rtc.h" #include "rtc.h"
/// \module time - time related functions
///
/// The `time` module provides functions for getting the current time and date,
/// and for sleeping.
STATIC const uint16_t days_since_jan1[]= { 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334 }; STATIC const uint16_t days_since_jan1[]= { 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334 };
STATIC bool is_leap_year(mp_uint_t year) { STATIC bool is_leap_year(mp_uint_t year) {
...@@ -64,8 +69,9 @@ mp_uint_t mod_time_seconds_since_2000(mp_uint_t year, mp_uint_t month, mp_uint_t ...@@ -64,8 +69,9 @@ mp_uint_t mod_time_seconds_since_2000(mp_uint_t year, mp_uint_t month, mp_uint_t
+ (year - 2000) * 31536000; + (year - 2000) * 31536000;
} }
// returns time stored in RTC as: (year, month, date, hour, minute, second, weekday) /// \function localtime()
// weekday is 0-6 for Mon-Sun /// Returns time stored in RTC as: (year, month, date, hour, minute, second, weekday).
/// Weekday is 0-6 for Mon-Sun.
STATIC mp_obj_t time_localtime(void) { STATIC mp_obj_t time_localtime(void) {
// get date and time // get date and time
// note: need to call get time then get date to correctly access the registers // note: need to call get time then get date to correctly access the registers
...@@ -87,6 +93,9 @@ STATIC mp_obj_t time_localtime(void) { ...@@ -87,6 +93,9 @@ STATIC mp_obj_t time_localtime(void) {
} }
MP_DEFINE_CONST_FUN_OBJ_0(time_localtime_obj, time_localtime); MP_DEFINE_CONST_FUN_OBJ_0(time_localtime_obj, time_localtime);
/// \function sleep(seconds)
/// Sleep for the given number of seconds. Seconds can be a floating-point number to
/// sleep for a fractional number of seconds.
STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) { STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) {
#if MICROPY_PY_BUILTINS_FLOAT #if MICROPY_PY_BUILTINS_FLOAT
if (MP_OBJ_IS_INT(seconds_o)) { if (MP_OBJ_IS_INT(seconds_o)) {
...@@ -101,7 +110,8 @@ STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) { ...@@ -101,7 +110,8 @@ STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) {
} }
MP_DEFINE_CONST_FUN_OBJ_1(time_sleep_obj, time_sleep); MP_DEFINE_CONST_FUN_OBJ_1(time_sleep_obj, time_sleep);
// returns the number of seconds, as an integer, since 1/1/2000 /// \function time()
/// Returns the number of seconds, as an integer, since 1/1/2000.
STATIC mp_obj_t time_time(void) { STATIC mp_obj_t time_time(void) {
// get date and time // get date and time
// note: need to call get time then get date to correctly access the registers // note: need to call get time then get date to correctly access the registers
......
...@@ -589,7 +589,7 @@ STATIC mp_obj_t pin_af_index(mp_obj_t self_in) { ...@@ -589,7 +589,7 @@ STATIC mp_obj_t pin_af_index(mp_obj_t self_in) {
} }
STATIC MP_DEFINE_CONST_FUN_OBJ_1(pin_af_index_obj, pin_af_index); STATIC MP_DEFINE_CONST_FUN_OBJ_1(pin_af_index_obj, pin_af_index);
/// \method index() /// \method name()
/// Return the name of the alternate function. /// Return the name of the alternate function.
STATIC mp_obj_t pin_af_name(mp_obj_t self_in) { STATIC mp_obj_t pin_af_name(mp_obj_t self_in) {
pin_af_obj_t *af = self_in; pin_af_obj_t *af = self_in;
...@@ -597,7 +597,7 @@ STATIC mp_obj_t pin_af_name(mp_obj_t self_in) { ...@@ -597,7 +597,7 @@ STATIC mp_obj_t pin_af_name(mp_obj_t self_in) {
} }
STATIC MP_DEFINE_CONST_FUN_OBJ_1(pin_af_name_obj, pin_af_name); STATIC MP_DEFINE_CONST_FUN_OBJ_1(pin_af_name_obj, pin_af_name);
/// \method index() /// \method reg()
/// Return the base register associated with the peripheral assigned to this /// Return the base register associated with the peripheral assigned to this
/// alternate function. For example, if the alternate function were TIM2_CH3 /// alternate function. For example, if the alternate function were TIM2_CH3
/// this would return stm.TIM2 /// this would return stm.TIM2
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment