From ea439e59d95bee29df770dadbbc1a330d1e864a1 Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 8 Aug 2014 23:30:01 +0100 Subject: [PATCH] stmhal: Start of documentation for modos and modtime. --- stmhal/modos.c | 33 +++++++++++++++++++++++++++++++++ stmhal/modtime.c | 16 +++++++++++++--- stmhal/pin.c | 4 ++-- 3 files changed, 48 insertions(+), 5 deletions(-) diff --git a/stmhal/modos.c b/stmhal/modos.c index 67e020df9f..e8bbde8d90 100644 --- a/stmhal/modos.c +++ b/stmhal/modos.c @@ -41,6 +41,19 @@ #include "sdcard.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 static char lfn[_MAX_LFN + 1]; /* Buffer to store the LFN */ #endif @@ -54,6 +67,8 @@ STATIC bool sd_in_root(void) { #endif } +/// \function chdir(path) +/// Change current directory. STATIC mp_obj_t os_chdir(mp_obj_t path_in) { const char *path; path = mp_obj_str_get_str(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); +/// \function getcwd() +/// Get the current directory. STATIC mp_obj_t os_getcwd(void) { char buf[MICROPY_ALLOC_PATH_MAX + 1]; FRESULT res = f_getcwd(buf, sizeof buf); @@ -85,6 +102,8 @@ STATIC mp_obj_t os_getcwd(void) { } 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) { bool is_str_type = true; const char *path; @@ -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); +/// \function mkdir(path) +/// Create a new directory. STATIC mp_obj_t os_mkdir(mp_obj_t path_o) { const char *path = mp_obj_str_get_str(path_o); FRESULT res = f_mkdir(path); @@ -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); +/// \function remove(path) +/// Remove a file. STATIC mp_obj_t os_remove(mp_obj_t 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 @@ -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); +/// \function rmdir(path) +/// Remove a directory. STATIC mp_obj_t os_rmdir(mp_obj_t 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 @@ -217,6 +242,8 @@ STATIC bool path_equal(const char *path, const char *path_canonical) { 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) { const char *path = mp_obj_str_get_str(path_in); @@ -278,6 +305,8 @@ error: } STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_stat_obj, os_stat); +/// \function sync() +/// Sync all filesystems. STATIC mp_obj_t os_sync(void) { storage_flush(); return mp_const_none; @@ -285,6 +314,9 @@ STATIC mp_obj_t os_sync(void) { STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync); #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) { mp_int_t n = mp_obj_get_int(num); byte *data; @@ -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 }, + /// \constant sep - separation character used in paths { MP_OBJ_NEW_QSTR(MP_QSTR_sep), MP_OBJ_NEW_QSTR(MP_QSTR__slash_) }, #if MICROPY_HW_ENABLE_RNG diff --git a/stmhal/modtime.c b/stmhal/modtime.c index f13bb15f84..bdea1f4c3d 100644 --- a/stmhal/modtime.c +++ b/stmhal/modtime.c @@ -34,6 +34,11 @@ #include "portmodules.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 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 + (year - 2000) * 31536000; } -// returns time stored in RTC as: (year, month, date, hour, minute, second, weekday) -// weekday is 0-6 for Mon-Sun +/// \function localtime() +/// 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) { // get date and time // 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) { } 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) { #if MICROPY_PY_BUILTINS_FLOAT if (MP_OBJ_IS_INT(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); -// 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) { // get date and time // note: need to call get time then get date to correctly access the registers diff --git a/stmhal/pin.c b/stmhal/pin.c index 0271ced30f..fb50d3db13 100644 --- a/stmhal/pin.c +++ b/stmhal/pin.c @@ -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); -/// \method index() +/// \method name() /// Return the name of the alternate function. STATIC mp_obj_t pin_af_name(mp_obj_t 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) { } 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 /// alternate function. For example, if the alternate function were TIM2_CH3 /// this would return stm.TIM2