From d1bccf8be0cca29b07871ec727f90dd27add648d Mon Sep 17 00:00:00 2001 From: Winford Date: Sun, 9 Jul 2023 00:07:59 -0700 Subject: [PATCH] Documentation updates Adds sections for STM32 and Raspberry Pi Pico to the Getting Started Guide. Various libAtomVM api documentaion corrections. Fix warings about depreciated doxyen configuration options. Update `data_structures`, `functions`, `macros`, and `types` index files with new and removed entries to reflect recent api changes. Signed-off-by: Winford --- README.STM32.Md | 63 ++++++--- doc/Doxyfile.in | 130 ------------------ doc/src/apidocs/libatomvm/data_structures.rst | 39 +++++- doc/src/apidocs/libatomvm/functions.rst | 47 ++++++- doc/src/apidocs/libatomvm/macros.rst | 47 ++++++- doc/src/apidocs/libatomvm/types.rst | 14 +- doc/src/build-instructions.md | 72 +++++++++- doc/src/getting-started-guide.md | 111 ++++++++++++++- src/libAtomVM/avmpack.h | 12 +- src/libAtomVM/bitstring.h | 1 - src/libAtomVM/context.h | 2 +- src/libAtomVM/externalterm.h | 12 +- src/libAtomVM/globalcontext.h | 6 +- src/libAtomVM/iff.h | 2 +- src/libAtomVM/interop.h | 6 +- src/libAtomVM/mailbox.h | 5 +- src/libAtomVM/memory.h | 5 +- src/libAtomVM/module.h | 6 +- src/libAtomVM/scheduler.h | 6 +- src/libAtomVM/smp.h | 4 +- src/libAtomVM/sys.h | 9 +- src/libAtomVM/term.h | 17 +-- 22 files changed, 405 insertions(+), 211 deletions(-) diff --git a/README.STM32.Md b/README.STM32.Md index 416e24ed2..9ffcc6389 100644 --- a/README.STM32.Md +++ b/README.STM32.Md @@ -7,41 +7,60 @@ # AtomVM for STM32 ## Prerequisites -To flash both AtomVM and your packed AVM you must use st-flash (https://github.com/texane/stlink). Make sure to -follow its [installation procedure](https://github.com/texane/stlink#installation) before proceeding further. + +* [st-flash](https://github.com/texane/stlink), to flash both AtomVM and your packed AVM applications. Make sure to follow its [installation procedure](https://github.com/texane/stlink#installation) before proceeding further. +* arm-none-eabi/arm-elf toolchain compatible with your system +* `cmake` +* `make` +* A serial console program, such as `minicom` or `screen`, so that you can view console output from your AtomVM application. ## Building -- `git clone libopencm3` -- `cd libopencm3 && make -j4 && cd ..` -- `mkdir build` -- `cd build` -- `cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake -DLIBOPENCM3_DIR=../libopencm3 ..` -- `make` +Before building for the first time you need to have a compiled clone of the libopencm3 libraries, from inside the AtomVM/src/platforms/stm32 directory: + + $ git clone https://github.com/libopencm3/libopencm3.git + $ cd libopencm3 && make -j4 && cd .. + $ mkdir build + $ cd build + $ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake + $ make + +You can put libopencm3 wherever you want on your PC as long as you update LIBOPENCM3_DIR to point to it. This example assumes it has been cloned into /opt/libopencm3 and built. From inside the AtomVM/src/platforms/stm32 directory: -You can put libopencm3 wherever you want on your PC as long as you update LIBOPENCM3_DIR to point to it. + $ mkdir build + $ cd build + $ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake -DLIBOPENCM3_DIR=/opt/libopencm3 .. + $ make ## Flashing To flash AtomVM, use -``` -st-flash --reset write atom-vm.bin 0x8000000 -``` + + $ st-flash --reset write AtomVM-stm32f407vgt6.bin 0x8000000 To flash your packed AVM, use -``` -st-flash --reset write /path/to/your/packed.avm 0x8080000 -``` -Right now AtomVM expects to find the AVM at the address 0x808000. On a STM32 Discovery board this means that -the 1MB of flash will be split in 512KB available for the program and 512KB available for the packed AVM. -If for any reason you want to modify this, you can change `AVM_ADDRESS` and `AVM_FLASH_MAX_SIZE` defines in `main.c`. + $ st-flash --reset write /path/to/your/packed.avm 0x8080000 -# Printing -By default, stdout and stderr are printed on USART2. On the STM32F4Discovery board, you can see them -using a TTL-USB with the TX pin connected to board's pin PA2 (USART2 RX). Baudrate is 115200 and serial transmission -is 8N1 with no flow control. +You must include the atomvmlib.avm with your application when using packbeam, and it should be pruned: + + $ packbeam create -p -i application.avm application.beam /path/to/AtomVM/build/libs/atomvmlib.avm + +> Note: The option`-i` will instruct packbeam to include file names and line numbers in stack traces. This makes debugging applications far easier, but also increases size, so it may be omitted if desired. The `-p` option should be used, it instructs packbeam to prune the unused functions from the packed `.avm` file, and is strongly recommended. + +AtomVM expects to find the AVM at the address 0x808000. On a STM32 Discovery board this means that the 1MB of flash will be split in 512KB available for the program and 512KB available for the packed AVM. If for any reason you want to modify this, you can change `AVM_ADDRESS` and `AVM_FLASH_MAX_SIZE` defines in `main.c`. ## Changing device The default build is based on the STM32F4Discovery board chip (`stm32f407vgt6`). If you want to target a different chip, pass the `-DDEVICE` flag when invoking cmake. For example, to use the STM32F429Discovery, pass `-DDEVICE=stm32f429zit6` + +If you are building for a different target board the `CLOCK_FREQUENCY` definition in main.c will need to be changed to match the clock frequency (in hertz) of your cpu. + +The rcc_clock_setup_XXX_XXX will also need to be changed to match your particular chip-set. Consult [ST's documentation](https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html) for appropriate settings. + +## Printing +By default, stdout and stderr are printed on USART2. On the STM32F4Discovery board, you can see them +using a TTL-USB with the TX pin connected to board's pin PA2 (USART2 RX). Baudrate is 115200 and serial transmission +is 8N1 with no flow control. + +> If building for a different target USART and gpio pins may need to be adjusted in `main.c`. diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 44b0edcad..d18997304 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -97,14 +97,6 @@ ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English -# The OUTPUT_TEXT_DIRECTION tag is used to specify the direction in which all -# documentation generated by doxygen is written. Doxygen will use this -# information to generate all generated output in the proper direction. -# Possible values are: None, LTR, RTL and Context. -# The default value is: None. - -OUTPUT_TEXT_DIRECTION = None - # If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. @@ -257,12 +249,6 @@ TAB_SIZE = 4 ALIASES = -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -TCL_SUBST = - # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all @@ -1109,13 +1095,6 @@ VERBATIM_HEADERS = YES ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -1243,15 +1222,6 @@ HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 -# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting this -# to YES can help to show when doxygen was last run and thus if the -# documentation is up to date. -# The default value is: NO. -# This tag requires that the tag GENERATE_HTML is set to YES. - -HTML_TIMESTAMP = NO - # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML # documentation will contain a main index with vertical navigation menus that # are dynamically created via Javascript. If disabled, the navigation index will @@ -1533,16 +1503,6 @@ EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANSPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are not -# supported properly for IE 6.0, but are supported on all modern browsers. -# -# Note that when changing this option you need to delete any form_*.png files in -# the HTML output directory before the changes have effect. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. - -FORMULA_TRANSPARENT = YES # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # https://www.mathjax.org) which uses client side Javascript for the rendering @@ -1835,16 +1795,6 @@ LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source -# code with syntax highlighting in the LaTeX output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_SOURCE_CODE = NO - # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See # https://en.wikipedia.org/wiki/BibTeX and \cite for more info. @@ -1853,14 +1803,6 @@ LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain -# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated -# page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_TIMESTAMP = NO - # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute) # path from which the emoji images will be read. If a relative path is entered, # it will be relative to the LATEX_OUTPUT directory. If left blank the @@ -1925,16 +1867,6 @@ RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = -# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code -# with syntax highlighting in the RTF output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_RTF is set to YES. - -RTF_SOURCE_CODE = NO - #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- @@ -2031,15 +1963,6 @@ GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook -# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the -# program listings (including syntax highlighting and cross-referencing -# information) to the DOCBOOK output. Note that enabling this will significantly -# increase the size of the DOCBOOK output. -# The default value is: NO. -# This tag requires that the tag GENERATE_DOCBOOK is set to YES. - -DOCBOOK_PROGRAMLISTING = NO - #--------------------------------------------------------------------------- # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- @@ -2214,34 +2137,10 @@ EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of 'which perl'). -# The default file (with absolute path) is: /usr/bin/perl. - -PERL_PATH = /usr/bin/perl - #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram -# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to -# NO turns the diagrams off. Note that this option also works with HAVE_DOT -# disabled, but it is recommended to install and use dot, since it yields more -# powerful graphs. -# The default value is: YES. - -CLASS_DIAGRAMS = YES - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see: -# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. @@ -2274,23 +2173,6 @@ HAVE_DOT = YES DOT_NUM_THREADS = 0 -# When you want a differently looking font in the dot files that doxygen -# generates you can specify the font name using DOT_FONTNAME. You need to make -# sure dot is able to find the font, which can be done by putting it in a -# standard location or by setting the DOTFONTPATH environment variable or by -# setting DOT_FONTPATH to the directory containing the font. -# The default value is: Helvetica. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_FONTNAME = Helvetica - -# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of -# dot graphs. -# Minimum value: 4, maximum value: 24, default value: 10. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_FONTSIZE = 10 - # By default doxygen will tell dot to use the default font as specified with # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set # the path where dot can find it using this tag. @@ -2503,18 +2385,6 @@ DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not seem -# to support this out of the box. -# -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). -# The default value is: NO. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_TRANSPARENT = NO - # Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) support diff --git a/doc/src/apidocs/libatomvm/data_structures.rst b/doc/src/apidocs/libatomvm/data_structures.rst index 92496169d..ff3f4164d 100644 --- a/doc/src/apidocs/libatomvm/data_structures.rst +++ b/doc/src/apidocs/libatomvm/data_structures.rst @@ -11,20 +11,54 @@ Data Strucures .. doxygenstruct:: AtomsHashTable .. doxygenstruct:: AtomStringIntPair -.. doxygenstruct:: CContext +.. doxygenstruct:: AVMPackData +.. doxygenstruct:: AVMPackInfo +.. doxygenstruct:: BuiltInAtomRequestSignal +.. doxygenstruct:: BuiltInAtomSignal +.. doxygenstruct:: ConstAVMPack +.. doxygenstruct:: Context +.. doxygenstruct:: ContextAccumulator +.. doxygenstruct:: DictEntry +.. doxygenstruct:: ErlNifEnv +.. doxygenstruct:: ErlNifResourceTypeInit +.. doxygenstruct:: ExportedFunction +.. doxygenstruct:: FprintfFun +.. doxygenstruct:: GlobalContext .. doxygenstruct:: Heap .. doxygenstruct:: HeapFragment .. doxygenstruct:: HNode .. doxygenstruct:: IFFRecord +.. doxygenstruct:: InMemoryAVMPack +.. doxygenstruct:: Int24 +.. doxygenstruct:: Int40 +.. doxygenstruct:: Int48 +.. doxygenstruct:: Int56 +.. doxygenstruct:: kv_pair .. doxygenstruct:: LineRefOffset +.. doxygenstruct:: ListHead +.. doxygenstruct:: LiteralEntry .. doxygenstruct:: Mailbox .. doxygenstruct:: MailboxMessage .. doxygenstruct:: Message -.. doxygenstruct:: RegisteredProcess +.. doxygenstruct:: Module +.. doxygenstruct:: ModuleFilename +.. doxygenstruct:: ModuleFunction +.. doxygenstruct:: Monitor +.. doxygenstruct:: Nif +.. doxygenstruct:: PrinterFun .. doxygenstruct:: RefcBinary +.. doxygenstruct:: RefcBinaryAVMPack .. doxygenstruct:: RefSignal +.. doxygenstruct:: RegisteredProcess +.. doxygenstruct:: ResourceType +.. doxygenstruct:: SnprintfFun .. doxygenstruct:: SpinLock +.. doxygenstruct:: SyncList +.. doxygenstruct:: TempStack +.. doxygenstruct:: TermSignal .. doxygenstruct:: TimerList +.. doxygenstruct:: TimerListItem +.. doxygenstruct:: UnresolvedFunctionCall .. doxygenstruct:: ValuesHashTable .. toctree:: @@ -34,6 +68,7 @@ Data Strucures .. doxygenenum:: BitstringFlags .. doxygenenum:: ContextFlags .. doxygenenum:: DictionaryFunctionResult +.. doxygenenum:: ErlNifResourceFlags .. doxygenenum:: ExternalTermOpts .. doxygenenum:: ExternalTermResult .. doxygenenum:: FunctionType diff --git a/doc/src/apidocs/libatomvm/functions.rst b/doc/src/apidocs/libatomvm/functions.rst index 3c9ee3f01..f6993abc4 100644 --- a/doc/src/apidocs/libatomvm/functions.rst +++ b/doc/src/apidocs/libatomvm/functions.rst @@ -15,10 +15,13 @@ Functions .. doxygenfunction:: atomshashtable_get_value .. doxygenfunction:: atomshashtable_has_key .. doxygenfunction:: atomshashtable_insert +.. doxygenfunction:: atomshashtable_new .. doxygenfunction:: avmpack_find_section_by_flag .. doxygenfunction:: avmpack_find_section_by_name .. doxygenfunction:: avmpack_fold .. doxygenfunction:: avmpack_is_valid +.. doxygenfunction:: bitstring_extract_any_integer +.. doxygenfunction:: bitstring_insert_any_integer .. doxygenfunction:: bitstring_utf16_decode .. doxygenfunction:: bitstring_utf16_encode .. doxygenfunction:: bitstring_utf32_decode @@ -44,10 +47,17 @@ Functions .. doxygenfunction:: debug_dump_registers .. doxygenfunction:: debug_dump_stack .. doxygenfunction:: debug_print_processes_list +.. doxygenfunction:: defaultatoms_init .. doxygenfunction:: dictionary_destroy .. doxygenfunction:: dictionary_erase .. doxygenfunction:: dictionary_get .. doxygenfunction:: dictionary_put +.. doxygenfunction:: enif_alloc_resource +.. doxygenfunction:: enif_get_resource +.. doxygenfunction:: enif_init_resource_type +.. doxygenfunction:: enif_keep_resource +.. doxygenfunction:: enif_make_resource +.. doxygenfunction:: enif_release_resource .. doxygenfunction:: externalterm_from_binary .. doxygenfunction:: externalterm_to_binary .. doxygenfunction:: externalterm_to_term @@ -58,6 +68,7 @@ Functions .. doxygenfunction:: globalcontext_get_module .. doxygenfunction:: globalcontext_get_module_by_index .. doxygenfunction:: globalcontext_get_process_lock +.. doxygenfunction:: globalcontext_get_process_nolock .. doxygenfunction:: globalcontext_get_process_unlock .. doxygenfunction:: globalcontext_get_registered_process .. doxygenfunction:: globalcontext_init_process @@ -65,6 +76,7 @@ Functions .. doxygenfunction:: globalcontext_insert_atom_maybe_copy .. doxygenfunction:: globalcontext_insert_module .. doxygenfunction:: globalcontext_is_atom_index_equal_to_atom_string +.. doxygenfunction:: globalcontext_maybe_unregister_process_id .. doxygenfunction:: globalcontext_new .. doxygenfunction:: globalcontext_process_exists .. doxygenfunction:: globalcontext_register_process @@ -74,18 +86,24 @@ Functions .. doxygenfunction:: globalcontext_unregister_process .. doxygenfunction:: iff_is_valid_beam .. doxygenfunction:: interop_atom_term_select_int +.. doxygenfunction:: interop_atom_to_string +.. doxygenfunction:: interop_binary_to_string .. doxygenfunction:: interop_kv_get_value_default +.. doxygenfunction:: interop_list_to_string +.. doxygenfunction:: interop_map_get_value +.. doxygenfunction:: interop_map_get_value_default +.. doxygenfunction:: interop_proplist_get_value +.. doxygenfunction:: interop_proplist_get_value_default +.. doxygenfunction:: interop_term_to_string .. doxygenfunction:: mailbox_crashdump .. doxygenfunction:: mailbox_destroy .. doxygenfunction:: mailbox_first .. doxygenfunction:: mailbox_init .. doxygenfunction:: mailbox_len .. doxygenfunction:: mailbox_message_dispose -.. doxygenfunction:: mailbox_message_to_heap_fragment .. doxygenfunction:: mailbox_next .. doxygenfunction:: mailbox_peek .. doxygenfunction:: mailbox_process_outer_list -.. doxygenfunction:: mailbox_remove_message .. doxygenfunction:: mailbox_reset .. doxygenfunction:: mailbox_send .. doxygenfunction:: mailbox_send_built_in_atom_request_signal @@ -102,10 +120,16 @@ Functions .. doxygenfunction:: memory_init_heap .. doxygenfunction:: memory_init_heap_root_fragment .. doxygenfunction:: memory_sweep_mso_list +.. doxygenfunction:: module_destroy +.. doxygenfunction:: module_find_line +.. doxygenfunction:: module_get_function_from_label +.. doxygenfunction:: module_insert_line_ref_offset .. doxygenfunction:: module_load_literal .. doxygenfunction:: module_new_from_iff_binary .. doxygenfunction:: module_resolve_function .. doxygenfunction:: module_search_exported_function +.. doxygenfunction:: nifs_get +.. doxygenfunction:: platform_defaultatoms_init .. doxygenfunction:: platform_nifs_get_nif .. doxygenfunction:: port_ensure_available .. doxygenfunction:: port_heap_create_error_tuple @@ -118,16 +142,18 @@ Functions .. doxygenfunction:: port_is_standard_port_command .. doxygenfunction:: port_send_message .. doxygenfunction:: port_send_message_nolock +.. doxygenfunction:: posix_errno_to_term .. doxygenfunction:: refc_binary_create_binary_info -.. doxygenfunction:: refc_binary_create_refc +.. doxygenfunction:: refc_binary_create_resource .. doxygenfunction:: refc_binary_decrement_refcount +.. doxygenfunction:: refc_binary_destroy +.. doxygenfunction:: refc_binary_from_data .. doxygenfunction:: refc_binary_get_data .. doxygenfunction:: refc_binary_increment_refcount .. doxygenfunction:: refc_binary_total_size .. doxygenfunction:: reg_type_c .. doxygenfunction:: scan_iff .. doxygenfunction:: scheduler_cancel_timeout -.. doxygenfunction:: scheduler_entry_point .. doxygenfunction:: scheduler_init_ready .. doxygenfunction:: scheduler_kill .. doxygenfunction:: scheduler_next @@ -154,20 +180,33 @@ Functions .. doxygenfunction:: smp_rwlock_unlock .. doxygenfunction:: smp_rwlock_wrlock .. doxygenfunction:: smp_scheduler_start +.. doxygenfunction:: stacktrace_build +.. doxygenfunction:: stacktrace_create_raw .. doxygenfunction:: sys_create_port .. doxygenfunction:: sys_free_platform .. doxygenfunction:: sys_get_info .. doxygenfunction:: sys_init_platform +.. doxygenfunction:: sys_listener_destroy .. doxygenfunction:: sys_load_module +.. doxygenfunction:: sys_load_module_from_file +.. doxygenfunction:: sys_monotonic_millis .. doxygenfunction:: sys_monotonic_time +.. doxygenfunction:: sys_open_avm_from_file .. doxygenfunction:: sys_poll_events +.. doxygenfunction:: sys_register_listener .. doxygenfunction:: sys_signal .. doxygenfunction:: sys_time +.. doxygenfunction:: sys_unregister_listener .. doxygenfunction:: term_alloc_refc_binary .. doxygenfunction:: term_alloc_sub_binary .. doxygenfunction:: term_compare .. doxygenfunction:: term_display .. doxygenfunction:: term_fprint .. doxygenfunction:: term_funprint +.. doxygenfunction:: term_get_map_assoc .. doxygenfunction:: term_snprint .. doxygenfunction:: timer_list_next +.. doxygenfunction:: valueshashtable_get_value +.. doxygenfunction:: valueshashtable_has_key +.. doxygenfunction:: valueshashtable_insert +.. doxygenfunction:: valueshashtable_new \ No newline at end of file diff --git a/doc/src/apidocs/libatomvm/macros.rst b/doc/src/apidocs/libatomvm/macros.rst index c1655b83a..aad4f93ea 100644 --- a/doc/src/apidocs/libatomvm/macros.rst +++ b/doc/src/apidocs/libatomvm/macros.rst @@ -9,25 +9,49 @@ MACROS :maxdepth: 3 .. doxygendefine:: AT8U - .. doxygendefine:: ATOM_STR .. doxygendefine:: BEGIN_WITH_STACK_HEAP .. doxygendefine:: END_WITH_STACK_HEAP +.. doxygendefine:: CALL_FUN .. doxygendefine:: CODE .. doxygendefine:: CONTAINER_OF +.. doxygendefine:: DECODE_ALLOCATOR_LIST +.. doxygendefine:: DECODE_ATOM +.. doxygendefine:: DECODE_COMPACT_TERM +.. doxygendefine:: DECODE_DEST_REGISTER +.. doxygendefine:: DECODE_EXTENDED_LIST_TAG +.. doxygendefine:: DECODE_FLAGS_LIST +.. doxygendefine:: DECODE_FP_REGISTER +.. doxygendefine:: DECODE_INTEGER +.. doxygendefine:: DECODE_LABEL +.. doxygendefine:: DECODE_LITERAL +.. doxygendefine:: DECODE_VALUE +.. doxygendefine:: DECODE_XREG +.. doxygendefine:: DECODE_YREG +.. doxygendefine:: END_WITH_STACK_HEAP +.. doxygendefine:: ENDIAN_SWAP_32 .. doxygendefine:: EXPT .. doxygendefine:: FUNT .. doxygendefine:: GET_LIST_ENTRY .. doxygendefine:: IFF_SECTION_HEADER_SIZE .. doxygendefine:: IMPT +.. doxygendefine:: IS_EXTENDED_ALLOCATOR +.. doxygendefine:: IS_EXTENDED_FP_REGISTER +.. doxygendefine:: IS_NULL_PTR +.. doxygendefine:: JUMP_TO_ADDRESS +.. doxygendefine:: LIKELY .. doxygendefine:: LINT .. doxygendefine:: LIST_FOR_EACH -.. doxygendefine:: LITT .. doxygendefine:: LITU .. doxygendefine:: LOCT .. doxygendefine:: MAX_OFFS .. doxygendefine:: MAX_SIZES +.. doxygendefine:: MIN .. doxygendefine:: MUTABLE_LIST_FOR_EACH +.. doxygendefine:: NEXT_INSTRUCTION +.. doxygendefine:: NO_DISCARD +.. doxygendefine:: POINTER_TO_II +.. doxygendefine:: PRINTF_FORMAT_ARGS .. doxygendefine:: PROCESS_MAYBE_TRAP_RETURN_VALUE .. doxygendefine:: PROCESS_MAYBE_TRAP_RETURN_VALUE_LAST .. doxygendefine:: PROCESS_MAYBE_TRAP_RETURN_VALUE_RESTORE_I @@ -35,15 +59,34 @@ MACROS .. doxygendefine:: READ_16_UNALIGNED .. doxygendefine:: READ_32_ALIGNED .. doxygendefine:: READ_32_UNALIGNED +.. doxygendefine:: READ_DEST_REGISTER .. doxygendefine:: SCHEDULE_NEXT +.. doxygendefine:: SELECT_INT_DEFAULT .. doxygendefine:: SET_ERROR .. doxygendefine:: STRT .. doxygendefine:: SWAP_KV_PAIR +.. doxygendefine:: T_DEST_REG +.. doxygendefine:: TO_ATOMSHASHTABLE_VALUE +.. doxygendefine:: TRACE +.. doxygendefine:: TRACE_APPLY +.. doxygendefine:: TRACE_CALL +.. doxygendefine:: TRACE_CALL_EXT +.. doxygendefine:: TRACE_RECEIVE +.. doxygendefine:: TRACE_RETURN +.. doxygendefine:: TRACE_SEND +.. doxygendefine:: UNLIKELY +.. doxygendefine:: UNUSED +.. doxygendefine:: USED_BY_TRACE .. doxygendefine:: VALIDATE_VALUE .. doxygendefine:: VERIFY_IS_ANY_INTEGER .. doxygendefine:: VERIFY_IS_BINARY .. doxygendefine:: VERIFY_IS_INTEGER .. doxygendefine:: VERIFY_IS_MATCH_OR_BINARY .. doxygendefine:: VERIFY_IS_MATCH_STATE +.. doxygendefine:: VM_ABORT .. doxygendefine:: WRITE_16_UNALIGNED +.. doxygendefine:: WRITE_16LE_UNALIGNED .. doxygendefine:: WRITE_32_UNALIGNED +.. doxygendefine:: WRITE_32LE_UNALIGNED +.. doxygendefine:: WRITE_64LE_UNALIGNED +.. doxygendefine:: WRITE_REGISTER diff --git a/doc/src/apidocs/libatomvm/types.rst b/doc/src/apidocs/libatomvm/types.rst index 97085b019..7e670bf1c 100644 --- a/doc/src/apidocs/libatomvm/types.rst +++ b/doc/src/apidocs/libatomvm/types.rst @@ -16,9 +16,16 @@ Types .. doxygentypedef:: avm_uint64_t .. doxygentypedef:: avm_uint_t .. doxygentypedef:: avmpack_fold_fun -.. doxygentypedef:: CContext .. doxygentypedef:: CondVar .. doxygentypedef:: dreg_t +.. doxygentypedef:: ERL_NIF_TERM +.. doxygentypedef:: ErlNifEnv +.. doxygentypedef:: ErlNifEvent +.. doxygentypedef:: ErlNifPid +.. doxygentypedef:: ErlNifResourceDtor +.. doxygentypedef:: ErlNifResourceType +.. doxygentypedef:: event_handler_t +.. doxygentypedef:: EventListener .. doxygentypedef:: func_ptr_t .. doxygentypedef:: GlobalContext .. doxygentypedef:: Heap @@ -29,7 +36,10 @@ Types .. doxygentypedef:: Mutex .. doxygentypedef:: native_handler_f .. doxygentypedef:: NativeHandlerResult +.. doxygentypedef:: NifImpl +.. doxygentypedef:: printer_function_t +.. doxygentypedef:: PrinterFun .. doxygentypedef:: RWLock .. doxygentypedef:: SpinLock .. doxygentypedef:: term -.. doxygentypedef:: term_ref +.. doxygentypedef:: timer_list_callback_t diff --git a/doc/src/build-instructions.md b/doc/src/build-instructions.md index 8e2afb428..f12e5fe4d 100644 --- a/doc/src/build-instructions.md +++ b/doc/src/build-instructions.md @@ -426,4 +426,74 @@ Example: ## Building for STM32 -> TODO +### Prerequisites + +* `arm-none-eabi`/`arm-elf` toolchain compatible with your system +* `cmake` +* `make` +* `git` +* [`libopencm3`](https://github.com/libopencm3/libopencm3) + +### Setup libopencm3 + +Before building for the first time you need to have a compiled clone of the libopencm3 libraries, from inside the AtomVM/src/platforms/stm32 directory: + + $ git clone https://github.com/libopencm3/libopencm3.git + $ cd libopencm3 && make -j4 && cd .. + +>Note: You can put libopencm3 wherever you want on your PC as long as you update LIBOPENCM3_DIR to point to it. This example assumes it has been cloned into /opt/libopencm3 and built. From inside the AtomVM/src/platforms/stm32 directory:``` + cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake -DLIBOPENCM3_DIR=/opt/libopencm3 .. + +### Build AtomVM + + $ mkdir build + $ cd build + $ cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-toolchain.cmake + $ make + +### Changing device + +The default build is based on the STM32F4Discovery board chip (`stm32f407vgt6`). If you want to target a different +chip, pass the `-DDEVICE` flag when invoking cmake. For example, to use the STM32F429Discovery, pass +`-DDEVICE=stm32f429zit6` + +If you are building for a different target board the `CLOCK_FREQUENCY` definition in main.c will need to be changed to match the clock frequency (in hertz) of your cpu. + +The rcc_clock_setup_XXX_XXX will also need to be changed to match your particular chip-set. Consult [ST's documentation](https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html) for appropriate settings. + +### Printing +By default, stdout and stderr are printed on USART2. On the STM32F4Discovery board, you can see them +using a TTL-USB with the TX pin connected to board's pin PA2 (USART2 RX). Baudrate is 115200 and serial transmission +is 8N1 with no flow control. + +> If building for a different target USART and gpio pins may need to be adjusted in `main.c`. + +## Building for Raspberry Pi Pico + +### Prerequisites + +* `cmake` +* `ninja` +* `Erlang/OTP` +* `Elixir` (optional) + +## AtomVM build steps + + cd src/platforms/rp2040/ + mkdir build + cd build + cmake .. -G Ninja + ninja + +> You may want to build with option `AVM_REBOOT_ON_NOT_OK` so Pico restarts on error. + +## libAtomVM build steps + +Build of standard libraries is part of the generic unix build. + +From the root of the project: + + mkdir build + cd build + cmake .. -G Ninja + ninja diff --git a/doc/src/getting-started-guide.md b/doc/src/getting-started-guide.md index 4dcaa673e..b638144c8 100644 --- a/doc/src/getting-started-guide.md +++ b/doc/src/getting-started-guide.md @@ -8,10 +8,10 @@ The getting started is broken up into the following sections: -* Getting Started on the ESP32 platform -* Getting Started on the STM32 platform -* Getting Started on the Raspberry Pi Pico platform -* Getting Started on the Generic UNIX platform +* [Getting Started on the ESP32 platform](#getting-started-on-the-esp32-platform) +* [Getting Started on the STM32 platform](#getting-started-on-the-stm32-platform) +* [Getting Started on the Raspberry Pi Pico platform](#getting-started-on-the-raspberry-pi-pico-platform) +* [Getting Started on the Generic UNIX platform](#getting-started-on-the-generic-unix-platform) ## Getting Started on the ESP32 platform @@ -209,11 +209,110 @@ Once the application has been flashed, you may connect to the ESP32 over the ser ## Getting Started on the STM32 platform -> TODO will se distribute a binary image for STM32? +AtomVM can run on a wide variety of STM32 chipsets available from [STMicroelectronics](https://www.st.com). The support is not nearly as mature as for the ESP32 platform, but work is ongoing, and pull requests are always welcome. At this time AtomVM will work on any board with a minimum of around 128k ram and 512k (1M recommended) flash. Simple applications and tests have been successfully run on a stm32f411ceu6 (A.K.A. Black Pill V2). These minimum requirements may need to be raised as platform support matures. + +### Prerequisites + +* [st-flash](https://github.com/texane/stlink), to flash both AtomVM and your packed AVM applications. Make sure to follow its [installation procedure](https://github.com/texane/stlink#installation) before proceeding further. +* [`packbeam`](https://github.com/atomvm/atomvm_packbeam) the AtomVM for packing and stripping `*.beam` files into the AtomVM `*.avm` format. +* A serial console program, such as `minicom` or `screen`, so that you can view console output from your AtomVM application. + +### Build an AtomVM binary +You will first need to build a binary configured for your processor and board layout. Consult the [Build Instruction for STM32](./build-instructions#building-for-stm32) + +### Flashing +To flash AtomVM, use + + $ st-flash --reset write AtomVM-stm32f407vgt6.bin 0x8000000 + +To flash your packed AVM, use + + $ st-flash --reset write /path/to/your/packed.avm 0x8080000 + +You must include the atomvmlib.avm with your application when using [packbeam](https://github.com/atomvm/atomvm_packbeam), and it should be pruned: + + $ packbeam create -p -i application.avm application.beam /path/to/AtomVM/build/libs/atomvmlib.avm + +> Note: The option`-i` will instruct packbeam to include file names and line numbers in stack traces. This makes debugging applications far easier, but also increases size, so it may be omitted if desired. The `-p` option should be used, it instructs packbeam to prune the unused functions from the packed `.avm` file, and is strongly recommended. + +AtomVM expects to find the AVM at the address 0x808000. On a STM32 Discovery board this means that the 1MB of flash will be split in 512KB available for the program and 512KB available for the packed AVM. If for any reason you want to modify this, you can change `AVM_ADDRESS` and `AVM_FLASH_MAX_SIZE` defines in `main.c`. + +### Printing +By default, stdout and stderr are printed on USART2. On the STM32F4Discovery board, you can see them +using a TTL-USB with the TX pin connected to board's pin PA2 (USART2 RX). Baudrate is 115200 and serial transmission +is 8N1 with no flow control. + +### Distributed Binaries +Due to the very large number of supported chipsets, the wide variety of board configurations, and the code changes required to support them, it is unlikely pre-built binaries will be available for the stm32 platform in the near future. Consult the [Build Instruction](./build-instructions#building-for-stm32) to create a binary compatible with your board. ## Getting Started on the Raspberry Pi Pico platform -> TODO +### Prerequisites + +None of these tools are strictly required, but all are recommended for easier development: +* [`rebar3`](https://rebar3.org) +* [`atomvm_rebar3_plugin`](https://github.com/atomvm/atomvm_rebar3_plugin) +* [`packbeam`](https://github.com/atomvm/atomvm_packbeam) the AtomVM for packing and stripping `*.beam` files into the AtomVM `*.avm` format. (included as part of the `atomvm_rebar3_plugin`) +* A serial console program, such as `minicom` or `screen`, so that you can view console output from your AtomVM application. + +### Building AtomVM for Raspberry Pico + +If you want to use a custom built VM for testing consult the [Build Instructions for Raspberry Pi Pico](./build-instructions#building-for-raspberry-pi-pico) + +### Installing AtomVM and programs on Raspberry Pico + +The approach consists in installing various uf2 files which include the +address they should be loaded to. + +You typically need three uf2 files: +- `AtomVM.uf2` for the VM +- `atomvmlib.uf2` for the standard libraries +- your application's uf2. + +We provide an escript-based (what else?) tool to build uf2 files called +`uf2tool` that you can use to bundle your `avm` into uf2. + +If you need to upgrade AtomVM or the standard libraries, simply copy them again. + +### Installing AtomVM on Raspberry Pico + +VM binary is file `AtomVM.uf2` - `src/platforms/rp2040/build/src/AtomVM.uf2` if build from source. Simply copy it +to the pico. The VM will crash because there is no application. + +### Installing atomvm library to Raspberry Pico + +AtomVM library must be installed as well. For Build instructions consult the Raspberry Pi Pico [libAtomVM build steps](./build-instructions#libatomvm-build-steps) + +#### Installing it + +The library to install is `atomvmlib.uf2`, `build/libs/atomvmlib.uf2` if build from source. Copy the library to the pico. + +### Running Hello Pico + +This example will print a Hello Pico message repeatedly. + +It is built into `build/examples/erlang/rp2040/hello_pico.uf2`. + +You can install it and then connect to the serial port with minicom. + +### Running your own BEAM code on Raspberry Pico + +You need to create an avm file using the `packbeam` tool the [`atomvm_rebar3_plugin`](https://github.com/atomvm/atomvm_rebar3_plugin). + + packbeam create -p -i packed.avm module.beam + +or + + rebar3 packbeam -p -i packed.avm module.beam + +Then the BEAM file must be converted to UF2. +The VM currently expects the application to be loaded at address 0x100A0000. + + ./uf2tool create -o packed.uf2 -s 0x100A0000 packed.avm + +Copy this UF2 to the Pico after you copied the VM (`AtomVM.uf2`) and the +standard libraries (`atomvmlib.uf2`). + ## Getting Started on the Generic UNIX platform diff --git a/src/libAtomVM/avmpack.h b/src/libAtomVM/avmpack.h index 9e1b0aa68..3bf026e10 100644 --- a/src/libAtomVM/avmpack.h +++ b/src/libAtomVM/avmpack.h @@ -88,13 +88,13 @@ extern const struct AVMPackInfo const_avm_pack_info; * @details Instances of this function are supplied to the avmpack_fold function, in order to * provide a callback mechanism for folding over the contents of the AVM binary. * @param accum The accumulator supplied by the application. - * @param section_ptr a pointer to the start of the AVM section (including the module header) - * @param section_size the size of the entire section (including the module header) + * @param section_ptr a pointer to the start of the AVM section (including the module header). + * @param section_size the size of the entire section (including the module header). * @param beam_ptr the start of the beam module portion of the section. This pointers starts immediately after * the (aligned) header. - * @param flags the section flags, as defined in the module header - * @param section_name the section name, as defined in the module header - * @return an acculator, which will be supplied to the next call to this function, and eventually returned from the avmpack_fold function. + * @param flags the section flags, as defined in the module header. + * @param section_name the section name, as defined in the module header. + * @return an accumulator, which will be supplied to the next call to this function, and eventually returned from the avmpack_fold function. */ typedef void *(*avmpack_fold_fun)(void *accum, const void *section_ptr, uint32_t section_size, const void *beam_ptr, uint32_t flags, const char *section_name); @@ -106,6 +106,7 @@ typedef void *(*avmpack_fold_fun)(void *accum, const void *section_ptr, uint32_t * @param flags_mask that will be matched against file sections. * @param ptr will point to the found file section. * @param size will be set to the file section size that has been found, if the section has not been found it will not be updated. + * @param name the section name, as defined in the module header. * @returns 1 if the file section has been found, 0 otherwise. */ int avmpack_find_section_by_flag(const void *avmpack_binary, uint32_t flags_mask, const void **ptr, uint32_t *size, const char **name); @@ -138,6 +139,7 @@ int avmpack_is_valid(const void *avmpack_binary, uint32_t size); * * @details This function will call the callback on each section of the AVM Pack, passing in * the current section of each module in the AVM binary to the supplied fold function. + * @param accum The accumulator supplied by the application. * @param avmpack_binary a pointer to an AVM Pack binary. * @param fold_fun function that will be called for each AVM section. */ diff --git a/src/libAtomVM/bitstring.h b/src/libAtomVM/bitstring.h index 39a31220c..60bb7baeb 100644 --- a/src/libAtomVM/bitstring.h +++ b/src/libAtomVM/bitstring.h @@ -478,7 +478,6 @@ static inline bool bitstring_match_utf16(term src_bin, size_t offset, int32_t *c * @param offset offset, in bits, to where to insert the character * @param c character to encode * @param bs_flags flags to encode the character (undefined/little/big/native) - * @param out_size the size in bytes, on output * @return \c true if encoding was successful, \c false if c is not a valid * unicode character */ diff --git a/src/libAtomVM/context.h b/src/libAtomVM/context.h index 72d2e1cc8..04750da37 100644 --- a/src/libAtomVM/context.h +++ b/src/libAtomVM/context.h @@ -288,7 +288,7 @@ static inline size_t context_avail_free_memory(const Context *ctx) * This function is just a shortcut that uses the corresponding funtion from globalcontext. * @param ctx the current Context. * @param atom_a any term of any type, when it is not an atom false is always returned. - * @param AtomString an atom string, which is the atom length followed by atom characters. + * @param atom_string_b an atom string, which is the atom length followed by atom characters. * @returns true if they both refer to the same atom, otherwise false. */ static inline bool context_is_term_equal_to_atom_string(Context *ctx, term atom_a, AtomString atom_string_b) diff --git a/src/libAtomVM/externalterm.h b/src/libAtomVM/externalterm.h index 131a6b220..0c33a6fa7 100644 --- a/src/libAtomVM/externalterm.h +++ b/src/libAtomVM/externalterm.h @@ -53,8 +53,9 @@ typedef enum * * @details Deserialize an external term from external format and returns a term. * @param external_term the external term that will be deserialized. + * @param size to allocate for term. * @param ctx the context that owns the memory that will be allocated. - * @param use_heap_fragment if non-zero, use a heap fragment to store the generated + * @param opts if non-zero, use a heap fragment to store the generated * terms. Otherwise, use the heap in the provided context. Note that when using the * context heap, this function may call the GC, if there is insufficient space to * store the generated terms. @@ -71,10 +72,9 @@ term externalterm_to_term( * allocate the instantiated terms. This function is the complement of externalterm_to_binary. * WARNING: This function may call the GC, which may render the input binary invalid. * @param ctx the context that owns the memory that will be allocated. - * @param binary the binary - * @param bytes_read the number of bytes read from the input binary - * @param num_extra_terms the number of words (terms) to (possibly) allocate space for - * in the heap, prior to instantiating the destination term (may trigger GC). + * @param dst a pointer to a term that will contain the binary encoded term. + * @param binary the binary. + * @param bytes_read the number of bytes read from the input binary. * @returns the term deserialized from the input term, or an invalid term, if * deserialization fails. */ @@ -88,7 +88,7 @@ enum ExternalTermResult externalterm_from_binary(Context *ctx, term *dst, term b * terms. This function is the complement of externalterm_to_binary. * WARNING: This function may call the GC, which may render the input binary invalid. * @param ctx the context that owns the memory that will be allocated. - * @param binary the binary + * @param t the term to return as binary. * @returns the term deserialized from the input term, or an invalid term, if * deserialization fails. */ diff --git a/src/libAtomVM/globalcontext.h b/src/libAtomVM/globalcontext.h index 47088045a..0b8c218e8 100644 --- a/src/libAtomVM/globalcontext.h +++ b/src/libAtomVM/globalcontext.h @@ -141,7 +141,7 @@ GlobalContext *globalcontext_new(); * @brief Destoys an existing GlobalContext * * @details Frees global context resources and memory and removes it from the processes table. - * @param c the global context that will be destroyed. + * @param glb the global context that will be destroyed. */ void globalcontext_destroy(GlobalContext *glb); @@ -290,7 +290,7 @@ int globalcontext_insert_atom_maybe_copy(GlobalContext *glb, AtomString atom_str * @details Checks if the given atom table index and the given AtomString refers to the same atom. * @param glb the global context. * @param atom_index_a an atom table index. - * @param AtomString an atom string, which is the atom length followed by atom characters. + * @param atom_string_b an atom string, which is the atom length followed by atom characters. * @returns true if they both refer to the same atom, otherwise false. */ bool globalcontext_is_atom_index_equal_to_atom_string(GlobalContext *glb, int atom_index_a, AtomString atom_string_b); @@ -301,7 +301,7 @@ bool globalcontext_is_atom_index_equal_to_atom_string(GlobalContext *glb, int at * @details Checks if the given term and the given AtomString refers to the same atom. * @param glb the global context. * @param atom_a any term of any type, when it is not an atom false is always returned. - * @param AtomString an atom string, which is the atom length followed by atom characters. + * @param atom_string_b an atom string, which is the atom length followed by atom characters. * @returns true if they both refer to the same atom, otherwise false. */ static inline bool globalcontext_is_term_equal_to_atom_string(GlobalContext *global, term atom_a, AtomString atom_string_b) diff --git a/src/libAtomVM/iff.h b/src/libAtomVM/iff.h index 049d62081..233fdd9cf 100644 --- a/src/libAtomVM/iff.h +++ b/src/libAtomVM/iff.h @@ -68,7 +68,7 @@ extern "C" { * @brief parse a BEAM/IFF file and build a sections offsets table * * @details Read a buffer containing a BEAM module file and set all found IFF sections into offsets array. - * @param data is BEAM module data. + * @param iff_binary is BEAM module data. * @param file_size is the BEAM module size in bytes. * @param offsets all the relative offsets, each entry will be set to the offset of a different IFF section. * @param sizes the computed sections sizes. diff --git a/src/libAtomVM/interop.h b/src/libAtomVM/interop.h index 76e70aa1c..7d3e9b129 100644 --- a/src/libAtomVM/interop.h +++ b/src/libAtomVM/interop.h @@ -71,10 +71,10 @@ NO_DISCARD InteropFunctionResult interop_write_iolist(term t, char *p); * @details Allows to quickly translate atoms to any integer constant. This function is useful for * creating switch statements for atom values. * A linear search is performed, so table entries should be sorted by frequency. - * @param glb the global context. * @param table an array AtomStringIntPair structs, teminated with a default entry marked with * SELECT_INT_DEFAULT macro. * @param atom the atom used for comparison. + * @param global the global context. * @returns the found int value which corresponds to the given atom. */ int interop_atom_term_select_int(const AtomStringIntPair *table, term atom, GlobalContext *global); @@ -87,7 +87,7 @@ int interop_atom_term_select_int(const AtomStringIntPair *table, term atom, Glob * @param kv any proplist or map. * @param key an AtomString, such as ATOM_STR("\x3", "key"). * @param default_value that is returned in case of missing item. - * + * @param glb the global context. * @returns the value term in case given key exists, otherwise the default_value. */ term interop_kv_get_value_default(term kv, AtomString key, term default_value, GlobalContext *glb); @@ -99,7 +99,7 @@ term interop_kv_get_value_default(term kv, AtomString key, term default_value, G * atom table. This function returns the invalid term if there is no such entry in kv. * @param kv any proplist or map. * @param key an AtomString, such as ATOM_STR("\x3", "key"). - * + * @param glb the global context. * @returns the value term in case given key exists, otherwise the invalid term. */ static inline term interop_kv_get_value(term kv, AtomString key, GlobalContext *glb) diff --git a/src/libAtomVM/mailbox.h b/src/libAtomVM/mailbox.h index aa1d34a83..91ffba061 100644 --- a/src/libAtomVM/mailbox.h +++ b/src/libAtomVM/mailbox.h @@ -139,7 +139,7 @@ typedef struct /** * @brief Initialize the mailbox * - * @param mbx the mailbox to initialize. + * @param mbox the mailbox to initialize. */ void mailbox_init(Mailbox *mbox); @@ -311,7 +311,8 @@ void mailbox_message_dispose(MailboxMessage *m, Heap *heap); * @details Discard a term that has been previously queued on a certain process * or driver mailbox. To be called from the process only. Term messages are * actually added as fragments to the heap and will be gone at next GC. - * @param mbx the mailbox to remove next message from. + * @param mbox the mailbox to remove next message from. + * @param heap the heap to add messages to. */ static inline void mailbox_remove_message(Mailbox *mbox, Heap *heap) { diff --git a/src/libAtomVM/memory.h b/src/libAtomVM/memory.h index 4c7ceba8c..4b7c73934 100644 --- a/src/libAtomVM/memory.h +++ b/src/libAtomVM/memory.h @@ -122,12 +122,14 @@ typedef struct Heap Heap; * * @param heap heap to initialize. * @param root fragment root. + * @param size capacity of the heap to create, including the mso_list. */ void memory_init_heap_root_fragment(Heap *heap, HeapFragment *root, size_t size); /** * @brief Initialize a root heap. * + * @param heap heap to initialize. * @param size capacity of the heap to create, including the mso_list. * @returns MEMORY_GC_OK or MEMORY_GC_ERROR_FAILED_ALLOCATION depending on the outcome. */ @@ -168,7 +170,7 @@ static inline size_t memory_heap_memory_size(const Heap *heap) * @brief allocates space for a certain amount of terms on the heap * * @details allocates space for a certain amount of terms on the heap, GC will be performed when needed, any existing term might be invalid after this call. - * @param ctx the context that owns the heap. + * @param heap heap to initialize. * @param size the amount of terms that will be allocated. * @returns a pointer to the newly allocated memory block. */ @@ -191,6 +193,7 @@ static inline MALLOC_LIKE term *memory_heap_alloc(Heap *heap, size_t size) * * @details deep copies a term to a destination heap, once finished old memory can be freed. * @param new_heap the destination heap where terms will be copied. + * @param t term to copy * @returns a new term that is stored on the new heap. */ term memory_copy_term_tree(Heap *new_heap, term t); diff --git a/src/libAtomVM/module.h b/src/libAtomVM/module.h index 61097d11d..c750d40da 100644 --- a/src/libAtomVM/module.h +++ b/src/libAtomVM/module.h @@ -160,7 +160,7 @@ void module_get_imported_function_module_and_name(const Module *this_module, int #endif /** - * @briefs Gets exported function index by searching it by function name and arity + * @brief Gets exported function index by searching it by function name and arity * * @details Gets exported function index by searching it by function name and arity * @param this_module the module on which the function will be searched. @@ -181,6 +181,7 @@ void module_destroy(Module *module); * @brief Parse a BEAM file and returns a Module * * @details Parse a BEAM file a returns a newly allocated and initialized Module struct. + * @param global the global context. * @param iff_binary the IFF file data. * @param size the size of the buffer containing the IFF data. */ @@ -192,6 +193,7 @@ Module *module_new_from_iff_binary(GlobalContext *global, const void *iff_binary * @details Loads and deserialize a term stored in the literal table and returns a term. * @param mod The module that owns that is going to be loaded. * @param index a valid literal index. + * @param ctx the target context. */ term module_load_literal(Module *mod, int index, Context *ctx); @@ -243,8 +245,8 @@ static inline term module_get_name(const Module *mod) * * @details Resolves an unresolved function reference and it replaces the unresolved reference with a ModuleFunction struct, * also it loads the referenced module if it hasn't been loaded yet. + * @param mod the module containing the function to resolve. * @param import_table_index the unresolved function index. - * @param func the unresolved function placeholder struct. */ static inline const struct ExportedFunction *module_resolve_function(Module *mod, int import_table_index) { diff --git a/src/libAtomVM/scheduler.h b/src/libAtomVM/scheduler.h index 094c7b015..7dd149371 100644 --- a/src/libAtomVM/scheduler.h +++ b/src/libAtomVM/scheduler.h @@ -69,14 +69,14 @@ void scheduler_signal_message(Context *c); /** * @brief Signal a process that it was killed. * - * @param c the process context. + * @param ctx the process context. */ void scheduler_kill(Context *ctx); /** * @brief removes a process and terminates it from the scheduling queue * - * @detail removes a process from the scheduling ready queue and destroys it if its not a leader process. + * @details removes a process from the scheduling ready queue and destroys it if its not a leader process. * @param c the process that is going to be terminated. */ void scheduler_terminate(Context *c); @@ -91,7 +91,7 @@ void scheduler_stop_all(GlobalContext *global); /** * @brief gets next runnable process from the ready queue. * - * @detail gets next runnable process from the ready queue, it may return current process if there isn't any other runnable process. + * @details gets next runnable process from the ready queue, it may return current process if there isn't any other runnable process. * @param global the global context. * @param c the current process. * @returns runnable process. diff --git a/src/libAtomVM/smp.h b/src/libAtomVM/smp.h index d32abede6..8ea1dc189 100644 --- a/src/libAtomVM/smp.h +++ b/src/libAtomVM/smp.h @@ -148,7 +148,7 @@ void smp_condvar_signal(CondVar *cv); /** * @brief Create a new rwlock. - * @detail A RW Lock can be replaced by a mutex if RW Lock are not available + * @details A RW Lock can be replaced by a mutex if RW Lock are not available * on the platform. * @return a pointer to a lock. */ @@ -214,7 +214,7 @@ static inline void smp_spinlock_unlock(SpinLock *lock) /** * @brief Get the number of online processors to configure schedulers. - * @detail This value is one plus the maximum number of times + * @details This value is one plus the maximum number of times * smp_scheduler_start will be called by the scheduler. * @return the number of online processors. */ diff --git a/src/libAtomVM/sys.h b/src/libAtomVM/sys.h index 0574248dc..374327c4d 100644 --- a/src/libAtomVM/sys.h +++ b/src/libAtomVM/sys.h @@ -199,17 +199,18 @@ Module *sys_load_module_from_file(GlobalContext *global, const char *path); /** * @brief Create a port driver - * @details This function creates a port driver, enscapsulated in a Context object. This function should + * @details This function creates a port driver, encapsulated in a Context object. This function should * create a Context object through the supplied global context, which will assume ownership of the new instance. - * @param glb the global context - * @param opts the term options passed into the port open command + * @param glb the global context. + * @param driver_name the name of the driver that will control the port. + * @param opts the term options passed into the port open command. * @return a new Context instance, or NULL, if a driver cannot be created from the inputs. */ Context *sys_create_port(GlobalContext *glb, const char *driver_name, term opts); /** * @brief Get platform-dependent information for the specified key. - * @details This function returns platform-depndent information specified by the supplied key. + * @details This function returns platform-dependent information specified by the supplied key. * If not information is available for the specified key, this function should return the * atom 'undefined' * @param ctx the current context diff --git a/src/libAtomVM/term.h b/src/libAtomVM/term.h index dabdbc86c..62b5d1bcb 100644 --- a/src/libAtomVM/term.h +++ b/src/libAtomVM/term.h @@ -150,9 +150,10 @@ extern const term empty_tuple; * @brief Compares two terms * * @details Tells if first term is >, < or == to the second term. - * @param t the first term - * @param other the second term - * @param global the global context + * @param t the first term. + * @param other the second term. + * @param opts a value of 1 will compare exact equality, 0 for less strict equality. + * @param global the global context. * @return any of TermEquals, TermLessThan, TermGreaterThan or TermCompareMemoryAllocFail error. */ TermCompareResult term_compare(term t, term other, TermCompareOpts opts, GlobalContext *global); @@ -318,7 +319,7 @@ static inline int term_is_movable_boxed(term t) * @brief Returns size of a boxed term from its header * * @details Returns the size that is stored in boxed term header most significant bits. - * @param t the boxed term header. + * @param header the boxed term header. * @return the size of the boxed term that follows the header. 0 is returned if the boxed term is just the header. */ static inline int term_get_size_from_boxed_header(term header) @@ -1081,8 +1082,8 @@ static inline term term_create_empty_binary(uint32_t size, Heap *heap, GlobalCon * at the bit position starting in offset. * @param t a term pointing to binary data. Fails if t is not a binary term. * @param offset the bitwise offset in t at which to start writing the integer value -* @param value the integer value to write -* @param n the bumber of low-order bits from value to write. +* @param src binary source to insert binary data into. +* @param n the number of low-order bits from value to write. * @return 0 on success; non-zero value if: * t is not a binary term * n is greater than the number of bits in an integer @@ -1268,7 +1269,7 @@ static inline term *term_get_list_ptr(term t) * @brief Gets list term from pointer * * @details Return given list term from a list element pointer. - * @param list_element a pointer to a list element. + * @param list_elem a pointer to a list element. * @return a list term */ static inline term term_list_from_list_ptr(term *list_elem) @@ -1420,7 +1421,7 @@ void term_display(FILE *fd, term t, const Context *ctx); * @brief Prints a term using given printer fun * * @details Print any given term using a printer fun - * @param fd the file where the term will be printed. + * @param pf function that will handle printing. * @param t the term that will be printed. * @param global the \c GlobalContext. * @returns the number of printed characters.