Skip to content

Commit ea439e5

Browse files
dpgeorgedpgeorge
committed
stmhal: Start of documentation for modos and modtime.
1 parent ef7a066 commit ea439e5

3 files changed

Lines changed: 48 additions & 5 deletions

File tree

‎stmhal/modos.c‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,19 @@
4141
#include "sdcard.h"
4242
#include "portmodules.h"
4343

44+
/// \module os - basic "operating system" services
45+
///
46+
/// The `os` module contains functions for filesystem access and `urandom`.
47+
///
48+
/// The filesystem has `/` as the root directory, and the available physical
49+
/// drives are accessible from here. They are currently:
50+
///
51+
/// /flash -- the internal flash filesystem
52+
/// /sd -- the SD card (if it exists)
53+
///
54+
/// On boot up, the current directory is `/flash` if no SD card is inserted,
55+
/// otherwise it is `/sd`.
56+
4457
#if _USE_LFN
4558
static char lfn[_MAX_LFN + 1]; /* Buffer to store the LFN */
4659
#endif
@@ -54,6 +67,8 @@ STATIC bool sd_in_root(void) {
5467
#endif
5568
}
5669

70+
/// \function chdir(path)
71+
/// Change current directory.
5772
STATIC mp_obj_t os_chdir(mp_obj_t path_in) {
5873
const char *path;
5974
path = mp_obj_str_get_str(path_in);
@@ -73,6 +88,8 @@ STATIC mp_obj_t os_chdir(mp_obj_t path_in) {
7388
}
7489
STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_chdir_obj, os_chdir);
7590

91+
/// \function getcwd()
92+
/// Get the current directory.
7693
STATIC mp_obj_t os_getcwd(void) {
7794
char buf[MICROPY_ALLOC_PATH_MAX + 1];
7895
FRESULT res = f_getcwd(buf, sizeof buf);
@@ -85,6 +102,8 @@ STATIC mp_obj_t os_getcwd(void) {
85102
}
86103
STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_getcwd_obj, os_getcwd);
87104

105+
/// \function listdir([dir])
106+
/// With no argument, list the current directory. Otherwise list the given directory.
88107
STATIC mp_obj_t os_listdir(uint n_args, const mp_obj_t *args) {
89108
bool is_str_type = true;
90109
const char *path;
@@ -161,6 +180,8 @@ STATIC mp_obj_t os_listdir(uint n_args, const mp_obj_t *args) {
161180
}
162181
STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(os_listdir_obj, 0, 1, os_listdir);
163182

183+
/// \function mkdir(path)
184+
/// Create a new directory.
164185
STATIC mp_obj_t os_mkdir(mp_obj_t path_o) {
165186
const char *path = mp_obj_str_get_str(path_o);
166187
FRESULT res = f_mkdir(path);
@@ -176,6 +197,8 @@ STATIC mp_obj_t os_mkdir(mp_obj_t path_o) {
176197
}
177198
STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_mkdir_obj, os_mkdir);
178199

200+
/// \function remove(path)
201+
/// Remove a file.
179202
STATIC mp_obj_t os_remove(mp_obj_t path_o) {
180203
const char *path = mp_obj_str_get_str(path_o);
181204
// 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) {
189212
}
190213
STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_remove_obj, os_remove);
191214

215+
/// \function rmdir(path)
216+
/// Remove a directory.
192217
STATIC mp_obj_t os_rmdir(mp_obj_t path_o) {
193218
const char *path = mp_obj_str_get_str(path_o);
194219
// 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) {
217242
return *path == '\0';
218243
}
219244

245+
/// \function stat(path)
246+
/// Get the status of a file or directory.
220247
STATIC mp_obj_t os_stat(mp_obj_t path_in) {
221248
const char *path = mp_obj_str_get_str(path_in);
222249

@@ -278,13 +305,18 @@ STATIC mp_obj_t os_stat(mp_obj_t path_in) {
278305
}
279306
STATIC MP_DEFINE_CONST_FUN_OBJ_1(os_stat_obj, os_stat);
280307

308+
/// \function sync()
309+
/// Sync all filesystems.
281310
STATIC mp_obj_t os_sync(void) {
282311
storage_flush();
283312
return mp_const_none;
284313
}
285314
STATIC MP_DEFINE_CONST_FUN_OBJ_0(os_sync_obj, os_sync);
286315

287316
#if MICROPY_HW_ENABLE_RNG
317+
/// \function urandom(n)
318+
/// Return a bytes object with n random bytes, generated by the hardware
319+
/// random number generator.
288320
STATIC mp_obj_t os_urandom(mp_obj_t num) {
289321
mp_int_t n = mp_obj_get_int(num);
290322
byte *data;
@@ -311,6 +343,7 @@ STATIC const mp_map_elem_t os_module_globals_table[] = {
311343

312344
{ MP_OBJ_NEW_QSTR(MP_QSTR_sync), (mp_obj_t)&os_sync_obj },
313345

346+
/// \constant sep - separation character used in paths
314347
{ MP_OBJ_NEW_QSTR(MP_QSTR_sep), MP_OBJ_NEW_QSTR(MP_QSTR__slash_) },
315348

316349
#if MICROPY_HW_ENABLE_RNG

‎stmhal/modtime.c‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,11 @@
3434
#include "portmodules.h"
3535
#include "rtc.h"
3636

37+
/// \module time - time related functions
38+
///
39+
/// The `time` module provides functions for getting the current time and date,
40+
/// and for sleeping.
41+
3742
STATIC const uint16_t days_since_jan1[]= { 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334 };
3843

3944
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
6469
+ (year - 2000) * 31536000;
6570
}
6671

67-
// returns time stored in RTC as: (year, month, date, hour, minute, second, weekday)
68-
// weekday is 0-6 for Mon-Sun
72+
/// \function localtime()
73+
/// Returns time stored in RTC as: (year, month, date, hour, minute, second, weekday).
74+
/// Weekday is 0-6 for Mon-Sun.
6975
STATIC mp_obj_t time_localtime(void) {
7076
// get date and time
7177
// 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) {
8793
}
8894
MP_DEFINE_CONST_FUN_OBJ_0(time_localtime_obj, time_localtime);
8995

96+
/// \function sleep(seconds)
97+
/// Sleep for the given number of seconds. Seconds can be a floating-point number to
98+
/// sleep for a fractional number of seconds.
9099
STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) {
91100
#if MICROPY_PY_BUILTINS_FLOAT
92101
if (MP_OBJ_IS_INT(seconds_o)) {
@@ -101,7 +110,8 @@ STATIC mp_obj_t time_sleep(mp_obj_t seconds_o) {
101110
}
102111
MP_DEFINE_CONST_FUN_OBJ_1(time_sleep_obj, time_sleep);
103112

104-
// returns the number of seconds, as an integer, since 1/1/2000
113+
/// \function time()
114+
/// Returns the number of seconds, as an integer, since 1/1/2000.
105115
STATIC mp_obj_t time_time(void) {
106116
// get date and time
107117
// note: need to call get time then get date to correctly access the registers

‎stmhal/pin.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -589,15 +589,15 @@ STATIC mp_obj_t pin_af_index(mp_obj_t self_in) {
589589
}
590590
STATIC MP_DEFINE_CONST_FUN_OBJ_1(pin_af_index_obj, pin_af_index);
591591

592-
/// \method index()
592+
/// \method name()
593593
/// Return the name of the alternate function.
594594
STATIC mp_obj_t pin_af_name(mp_obj_t self_in) {
595595
pin_af_obj_t *af = self_in;
596596
return MP_OBJ_NEW_QSTR(af->name);
597597
}
598598
STATIC MP_DEFINE_CONST_FUN_OBJ_1(pin_af_name_obj, pin_af_name);
599599

600-
/// \method index()
600+
/// \method reg()
601601
/// Return the base register associated with the peripheral assigned to this
602602
/// alternate function. For example, if the alternate function were TIM2_CH3
603603
/// this would return stm.TIM2

0 commit comments

Comments
 (0)