Skip to content

Commit

Permalink
Merge pull request #677 from UncleGrumpy/documentation_updates
Browse files Browse the repository at this point in the history 
Documentation updates
  • Loading branch information
@fadushin
fadushin authored Jul 10, 2023
2 parents fb4c8f0 + d1bccf8 commit 528b5e9
Show file tree
Hide file tree
Showing 22 changed files with 405 additions and 211 deletions.
63 changes: 41 additions & 22 deletions README.STM32.Md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
130 changes: 0 additions & 130 deletions doc/Doxyfile.in
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
#---------------------------------------------------------------------------
Expand Down Expand Up @@ -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
#---------------------------------------------------------------------------
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
39 changes: 37 additions & 2 deletions doc/src/apidocs/libatomvm/data_structures.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand All @@ -34,6 +68,7 @@ Data Strucures
.. doxygenenum:: BitstringFlags
.. doxygenenum:: ContextFlags
.. doxygenenum:: DictionaryFunctionResult
.. doxygenenum:: ErlNifResourceFlags
.. doxygenenum:: ExternalTermOpts
.. doxygenenum:: ExternalTermResult
.. doxygenenum:: FunctionType
Expand Down
Loading

0 comments on commit 528b5e9

Please sign in to comment.