This is an automated email from the ASF dual-hosted git repository.
xiaoxiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 4084c749c8 Documentation: add initial documentation page for SAMv7 MCU
4084c749c8 is described below
commit 4084c749c888703ef734279b923dab5884e33542
Author: Michal Lenc <[email protected]>
AuthorDate: Mon Mar 6 16:16:35 2023 +0100
Documentation: add initial documentation page for SAMv7 MCU
Initial documentation page for SAMv7 MCU is added. There are still
board pages to be added in the future.
Signed-off-by: Michal Lenc <[email protected]>
---
Documentation/platforms/arm/samv7/index.rst | 312 ++++++++++++++++++++++++++++
1 file changed, 312 insertions(+)
diff --git a/Documentation/platforms/arm/samv7/index.rst
b/Documentation/platforms/arm/samv7/index.rst
new file mode 100644
index 0000000000..1a33b4cbfc
--- /dev/null
+++ b/Documentation/platforms/arm/samv7/index.rst
@@ -0,0 +1,312 @@
+======
+SAM V7
+======
+
+This page contains information regarding MCUs series SAM E70, SAM S70, SAM V70
and SAMV71 made
+by Microchip. The series is based around and ARM Cortex-M7 core running up to
300 MHz.
+
+Microchip distinguishes those MCUs into three series SAM E, SAM S SAM V but
NuttX source code uses the
+same files and functions for all of those series and therefore they can be
merged into one category and
+named as SAM V7.
+
+Supported MCUs
+=============
+
+The following list includes MCUs from SAM x7 series and indicates whether they
are supported in NuttX
+
+======= ======= ============== =================
+MCU Support Core Frequency
+======= ======= ============== =================
+SAM E70 Yes Cortex-M7 300 MHz
+SAM S70 No Cortex-M7 300 MHz
+SAM V70 No Cortex-M7 300 MHz
+SAM V71 Yes Cortex-M7 300 MHz
+======= ======= ============== =================
+
+Data and Instruction Cache
+==========================
+
+MCUs in this series have separated caches for instructions and data, both 16
kB. Data cache is
+initially set as write-back but sometimes the configuration automatically
switch it to write-through
+mode. While write-back gives better performance, the reason of the switch are
the issues in some
+drivers that can arise because this mode is not correctly supported yet. This
happens for example
+when selecting ``CONFIG_SAMV7_EMAC`` (Ethernet MAC driver).
+
+Data chace can also be switched to write-through mode manually by setting
ARMV7M_DCACHE_WRITETHROUGH.
+
+Tickless OS
+===========
+
+With Tickless OS, the periodic, timer interrupt is eliminated and replaced
with a one-shot,
+interval timer, that becomes event driven instead of polled. This allows to
run the MCU with
+higher resolution without using more of the CPU bandwidth processing useless
interrupts.
+
+Current implementation only supports version with two timers: a one-shot that
provides the
+timed events and a free running timer that provides the current time.
Therefore two channels
+has to be used for tickless mode. ``CONFIG_USEC_PER_TICK`` option determines
the resolution
+of time reported by :c:func:`clock_systime_ticks()` and the resolution of
times that can be set
+for certain delays including watchdog timers and delayed work.
+
+The version (selected by ``CONFIG_SCHED_TICKLESS_ALARM``) with single free
running timer that provides
+current time and a capture/compare channel for timed events is not currently
supported. This would
+require just one channel, which can be useful in some MCUs that does not have
many channels.
+
+Peripheral Support
+==================
+
+The following list indicates peripherals supported in NuttX:
+
+========== =======
+Peripheral Support
+========== =======
+ACC No
+AES No
+AFEC Yes
+DACC Yes
+EEFC Yes
+GMAC Yes
+HSMCI Yes
+I2SC No
+ICM No
+ISI No
+MCAN Yes
+MLB No
+PMC No
+PWM Yes
+QSPI Yes
+SMC No
+SPI Yes
+SSC Yes
+TWIHS Yes
+TC Yes
+USART Yes
+WDT Yes
+XDMAC Yes
+========== =======
+
+Analog Comparator Controller (ACC)
+----------------------------------
+
+Analog Comparator Controller generates an interrupt based on user settngs. It
can also
+generate a compare event which can be used by the PWM driver.
+
+This peripheral is currently not supported.
+
+Advanced Encryption Standard (AES)
+----------------------------------
+
+The standard complies with the American FIPS Publication 197 specification. It
is not
+currently supported.
+
+Analog Front-End Controller (AFEC)
+----------------------------------
+
+This controller combines a 12 bit ADC, DAC and two 6 to 1 analog multiplexers.
The current
+support in NuttX implements the controller as an analog/digital converter that
can be trigger
+either via software trigger from the application or by timer/counter that runs
on a defined
+frequency. Triggering by PWM is also supported by the MCUs but not currently
implemented
+in NuttX. The lower-half of this driver is initialize by calling
:c:func:`sam_afec_initialize`
+
+Software trigger can be selected by ``CONFIG_SAMV7_AFECn_SWTRIG``,
timer/counter trigger by
+``CONFIG_SAMV7_AFECn_TIOATRIG``. It is also necessary to select corresponding
timer/counter
+(0 for AFEC0 and 1 for AFEC1) and enable corresponding channels. Triggering
from PWM driver
+is also supported and can be configured by ``CONFIG_SAMV7_AFECn_PWMTRIG``. In
this case
+subsequental configuration of PWM driver is required (see below in PWM
section).
+
+The 12 bit resolution mode can be extended up to a 16 bit resolution by
digital averaging.
+The averaging can be set by ``CONFIG_SAMV7_AFECn_RES``.
+
+The controller supports data transfer with DMA support which can be enabled by
``CONFIG_SAMV7_AFEC_DMA``.
+Option ``CONFIG_SAMV7_AFEC_DMASAMPLES`` then sets the number of samples to be
transfered.
+
+Digital/Analog Converter Controller (DACC)
+------------------------------------------
+
+Digital/Analog Converter supports 12 bit resolution and can operate in
free-running mode, maximum
+speed mode, trigger mode from timer/counter and interpolation mode. Trigger
mode is set by
+enabling ``CONFIG_SAMV7_DAC_TRIGGER`` option. The lower-half of this driver
is initialize by
+calling :c:func:`sam_dac_initialize`.
+
+DMA data transfer is supported by the controller but currently not implemented
in NuttX.
+
+Ethernet MAC (GMAC)
+-------------------
+
+This module implements a 10/100 Mbps Ethernet MAC which is compitible with the
IEEE 802.3 standard.
+Number of RR and TX buffers can be configured by
``CONFIG_SAMV7_EMAC0_NRXBUFFERS`` and
+``CONFIG_SAMV7_EMAC0_NTXBUFFERS`` respectively. Option
``CONFIG_SAMV7_EMAC0_PHYINIT`` may be selected
+when board specific initialization (GPIOs configuration, PHY reset etc.) is
required prior to
+module usage.
+
+High Speed Multimedia Card Interface (HSMCI)
+--------------------------------------------
+
+This module supports a hight speed connection to MultiMedia Cards (MMC).
Support for
+the SD slots can be enabled with the following settings:
+
+- System Type -> SAMV7 Peripheral Selection
+ - ``CONFIG_SAMV7_HSMCI0=y`` : To enable HSMCI0 support
+ - ``CONFIG_SAMV7_XDMAC=y`` : XDMAC is needed by HSMCI0/1
+
+- System Type
+ - ``CONFIG_SAMV7_GPIO_IRQ=y`` : PIO interrupts needed
+ - ``CONFIG_SAMV7_GPIOn_IRQ=y`` : Interrupt to corresponding
pin gate
+
+- Device Drivers -> MMC/SD Driver Support
+ - ``CONFIG_MMCSD=y`` : Enable MMC/SD support
+ - ``CONFIG_MMSCD_NSLOTS=1`` : One slot per driver instance
+ - ``CONFIG_MMCSD_MULTIBLOCK_DISABLE=y`` : (REVISIT)
+ - ``CONFIG_MMCSD_HAVE_CARDDETECT=y`` : Supports card-detect PIOs
+ - ``CONFIG_MMCSD_MMCSUPPORT=n`` : Interferes with some SD cards
+ - ``CONFIG_MMCSD_SPI=n`` : No SPI-based MMC/SD support
+ - ``CONFIG_MMCSD_SDIO=y`` : SDIO-based MMC/SD support
+ - ``CONFIG_SDIO_DMA=y`` : Use SDIO DMA
+ - ``CONFIG_SDIO_BLOCKSETUP=y`` : Needs to know block sizes
+
+- RTOS Features -> Work Queue Support
+ - ``CONFIG_SCHED_WORKQUEUE=y`` : Driver needs work queue
support
+
+- Application Configuration -> NSH Library
+ - ``CONFIG_NSH_ARCHINIT=y`` : NSH board-initialization, OR
+ - ``CONFIG_BOARD_LATE_INITIALIZE=y``
+
+The lower-half of this driver is initialized by calling
:c:func:`sdio_initialize`.
+
+Inter-IC Sound Interface (I2CS)
+-------------------------------
+
+This controller provides a 5 wire digital audio link to external audio
devices. The link
+is bidirectional and synchronous. The interface is compliant vit I2C
specification.
+
+This peripheral is currently not supported.
+
+Integrity Check Monitor (ICM)
+-----------------------------
+
+Integrity Check Monitor is a DMA controller that performs hash calculation
over memory
+regions.
+
+This peripheral is currently not supported.
+
+Image Sensor Interface (ISI)
+----------------------------
+
+This controller connects a CMOS type sensor to the MCU and provides image
captures is
+selected formatrs.
+
+This peripheral is currently not supported.
+
+Controller Area Network (MCAN)
+------------------------------
+
+Provides support for communication according to ISO 11898-1:2015 and to Bosch
CAN-FD
+specification. It is possible to select CAN FD communication in NuttX
configuration.
+
+The lower-half of the peripheral is initialized by function
:c:func:`sam_mcan_initialize`
+
+Media Local Bus (MLB)
+---------------------
+
+This peripheral maps all the MOST Network data types into a single interface.
+
+This peripheral is currently not supported.
+
+Power Management Controller (PMC)
+---------------------------------
+
+Peripheral used to optimize power consumption of MCU.
+
+Not yet supported.
+
+Pulse Width Modulation Controller (PWM)
+---------------------------------------
+
+Pulse Width Modulation Controller provides a PWM output on 4 independent
channels. Each channel
+can control two complementary outputs. PWM can also be used to generate a
signal that triggers
+ADC conversion. The trigger is generated from configurable comparison units.
These units can be
+set by config option ``CONFIG_SAMV7_PWMn_TRIGx`` where n is number of PWM
instance and x is the number
+of comparison unit.
+
+The peripheral has integrated fault protection that drives the output to zero
when activated. The
+protection activation can be trigger from various peripherals (ADC, PMC) or
from GPIO inputs.
+
+Furthemore PWM can impelement a dead time delays before the activation of
complementary outputs.
+These delays are turn on by ``CONFIG_PWM_DEADTIME`` while dead time values are
provided from application
+level the same way as duty cycle is set.
+
+The lower-half is initalized by function :c:func:`sam_pwminitialize`.
+
+Quad Serial Peripheral Interface (QSPI)
+---------------------------------------
+
+This peripheral provides communication with external devices in host mode
through synchronous serial
+data link. It is possible to use QSPI peripheral in SPI mode if this is
supported by MCU (config option
+``CONFIG_SAMV7_QSPI_SPI_MODE``).
+
+The lower-half is initalized by function :c:func:`sam_qspi_initialize` in case
of QSPI mode and by
+:c:func:`sam_qspi_spi_initialize` in case of SPI mode.
+
+Static Memory Controller (SMC)
+------------------------------
+
+This peripheral is a part of External Bus Interface (EBI) which is designed to
ensure the successful
+data transfer between several external devices and the microcontroller.
+
+This controller is currently not suported.
+
+Serial Peripheral Interface (SPI)
+---------------------------------
+
+This is a synchronous serial data link that provides communication with
external devices in host
+or client mode.
+
+The pripheral is initialized by :c:func:`sam_spibus_initialize` function.
+
+Synchronous Serial Controller (SSC)
+-----------------------------------
+
+This controller provides a synchronous communication link with external
devices.
+
+The controller is initialized by :c:func:`sam_ssc_initialize` function.
+
+Two Wire Interface (TWIHS)
+--------------------------
+
+It interconnects components on a two-wire bus. The bus is made up of one clock
line
+and one data line.
+
+Timer Counter (TC)
+------------------
+
+The peripheral implements four timer counter modules, each supporting three
independent channels.
+
+Universal Synchronous Asynchronous Receiver Transceiver (USART)
+---------------------------------------------------------------
+
+The MCU supports both UART and USART controllers. USART can be also used in
RS-485 mode (enabled
+by ``CONFIG_SAMV7_USARTx_RS485MODE`` option) or can be used with RX DMA
support. For this purpose it
+is required to configure idle bus timeout value in
``CONFIG_SAMV7_SERIAL_DMA_TIMEOUT``. This option
+ensures data are read from the DMA buffer even if it is not full yet. TX DMA
support is not implemented
+as well as entire DMA suport for UART peripheral.
+
+Watchdog Timer (WDT)
+---------------------
+
+The timer is used to prevent system lock-up if the software is trapped in a
deadlock.
+
+DMA Controller (XDMAC)
+----------------------
+
+This peripheral provides a central direct memory access controller which can
perform
+peripheral to memory or memory to memory transfers.
+
+Supported Boards
+================
+
+For board documentation please refer to ``board/arm/samv7`` section to
separate README files.
+
+.. toctree::
+ :glob:
+ :maxdepth: 1
+
+ boards/*/*
