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 @@
#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
......
......@@ -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
......
......@@ -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
......
Markdown is supported
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