1.. _v2m_musca_s1_board: 2 3ARM V2M Musca-S1 4################ 5 6Overview 7******** 8 9The v2m_musca_s1 board configuration is used by Zephyr applications that run 10on the V2M Musca-S1 board. It provides support for the Musca-S1 ARM Cortex-M33 11CPU and the following devices: 12 13- Nested Vectored Interrupt Controller (NVIC) 14- System Tick System Clock (SYSTICK) 15- Cortex-M System Design Kit GPIO 16- Cortex-M System Design Kit UART 17 18.. image:: img/v2m_musca_s1.jpg 19 :align: center 20 :alt: ARM V2M Musca-S1 21 22More information about the board can be found at the `V2M Musca-S1 Website`_. 23 24Hardware 25******** 26 27ARM V2M MUSCA-S1 provides the following hardware components: 28 29- ARM Cortex-M33 (with FPU and DSP) 30- ARM IoT Subsystem for Cortex-M33 31- Memory 32 33 - 512KB on-chip system memory SRAM. 34 - 2MB on-chip eMRAM (non-volatile). 35 - 32MB of external QSPI flash. 36 37- Debug 38 39 - JTAG, SWD & P-JTAG. 40 - DAPLink with a virtual UART port. 41 42- Arduino interface 43 44 - 16 3V3 or 1V8 GPIO. 45 - UART. 46 - SPI. 47 - I2C. 48 - I2S. 49 - 3-channel PWM. 50 - 6-channel analog interface. 51 52- On-board Peripherals 53 54 - User RGB LED. 55 - Gyro sensor. 56 - Combined ADC/DAC/temperature sensor. 57 58 59User push buttons 60================= 61 62The v2m_musca_s1 board provides the following user push buttons: 63 64- PBON: power on/off. 65- nSRST: Cortex-M33 system reset and CoreSight debug reset. 66- ISP: Updates DAPLink firmware. 67 68 69Supported Features 70=================== 71 72The v2m_musca_s1 board configuration supports the following hardware features: 73 74+-----------+------------+-------------------------------------+ 75| Interface | Controller | Driver/Component | 76+===========+============+=====================================+ 77| NVIC | on-chip | nested vector interrupt controller | 78+-----------+------------+-------------------------------------+ 79| SYSTICK | on-chip | systick | 80+-----------+------------+-------------------------------------+ 81| UART | on-chip | serial port-polling; | 82| | | serial port-interrupt | 83+-----------+------------+-------------------------------------+ 84| PINMUX | on-chip | pinmux | 85+-----------+------------+-------------------------------------+ 86| GPIO | on-chip | gpio | 87+-----------+------------+-------------------------------------+ 88| TIMER | on-chip | timer | 89+-----------+------------+-------------------------------------+ 90| TrustZone | on-chip | Trusted Firmware-M | 91+-----------+------------+-------------------------------------+ 92 93Other hardware features are not currently supported by the port. 94See the `V2M Musca-S1 Website`_ for a complete list of V2M Musca-S1 board 95hardware features. 96 97The default configuration can be found in the defconfig file: 98``boards/arm/v2m_musca_s1/v2m_musca_s1_defconfig``. 99 100Interrupt Controller 101==================== 102 103Musca-S1 is a Cortex-M33 based SoC and has 15 fixed exceptions and 77 IRQs. 104 105A Cortex-M33-based board uses vectored exceptions. This means each exception 106calls a handler directly from the vector table. 107 108Zephyr provides handlers for exceptions 1-7, 11, 12, 14, and 15, as listed 109in the following table: 110 111+------+------------+----------------+--------------------------+ 112| Exc# | Name | Remarks | Used by Zephyr Kernel | 113+======+============+================+==========================+ 114| 1 | Reset | | system initialization | 115+------+------------+----------------+--------------------------+ 116| 2 | NMI | | system fatal error | 117+------+------------+----------------+--------------------------+ 118| 3 | Hard fault | | system fatal error | 119+------+------------+----------------+--------------------------+ 120| 4 | MemManage | MPU fault | system fatal error | 121+------+------------+----------------+--------------------------+ 122| 5 | Bus | | system fatal error | 123+------+------------+----------------+--------------------------+ 124| 6 | Usage | Undefined | system fatal error | 125| | fault | instruction, | | 126| | | or switch | | 127| | | attempt to ARM | | 128| | | mode | | 129+------+------------+----------------+--------------------------+ 130| 7 | SecureFault| Unauthorized | system fatal error | 131| | | access to | | 132| | | secure region | | 133| | | from ns space | | 134+------+------------+----------------+--------------------------+ 135| 8 | Reserved | | not handled | 136+------+------------+----------------+--------------------------+ 137| 9 | Reserved | | not handled | 138+------+------------+----------------+--------------------------+ 139| 10 | Reserved | | not handled | 140+------+------------+----------------+--------------------------+ 141| 11 | SVC | | system calls, kernel | 142| | | | run-time exceptions, | 143| | | | and IRQ offloading | 144+------+------------+----------------+--------------------------+ 145| 12 | Debug | | system fatal error | 146| | monitor | | | 147+------+------------+----------------+--------------------------+ 148| 13 | Reserved | | not handled | 149+------+------------+----------------+--------------------------+ 150| 14 | PendSV | | context switch | 151+------+------------+----------------+--------------------------+ 152| 15 | SYSTICK | | system clock | 153+------+------------+----------------+--------------------------+ 154| 16 | Reserved | | not handled | 155+------+------------+----------------+--------------------------+ 156| 17 | Reserved | | not handled | 157+------+------------+----------------+--------------------------+ 158| 18 | Reserved | | not handled | 159+------+------------+----------------+--------------------------+ 160 161Pin Mapping 162=========== 163 164The ARM V2M Musca-S1 board's GPIO controller is responsible for pin-muxing, 165input/output, pull-up, etc. 166All GPIO controller pins are exposed via pins 0 - 15. 167 168Mapping from the ARM V2M Musca-S1 Board pins to GPIO controller pins: 169 170.. rst-class:: rst-columns 171 172 - D0 : P0_0 173 - D1 : P0_1 174 - D2 : P0_2 175 - D3 : P0_3 176 - D4 : P0_4 177 - D5 : P0_5 178 - D6 : P0_6 179 - D7 : P0_7 180 - D8 : P0_8 181 - D9 : P0_9 182 - D10 : P0_10 183 - D11 : P0_11 184 - D12 : P0_12 185 - D13 : P0_13 186 - D14 : P0_14 187 - D15 : P0_15 188 189Peripheral Mapping: 190 191.. rst-class:: rst-columns 192 193 - UART_0_RX : D0 194 - UART_0_TX : D1 195 - SPI_0_CS : D10 196 - SPI_0_MOSI : D11 197 - SPI_0_MISO : D12 198 - SPI_0_SCLK : D13 199 - I2C_0_SDA : D14 200 - I2C_0_SCL : D15 201 202For mode details please refer to `Musca-S1 Technical Reference Manual (TRM)`_. 203 204 205RGB LED 206============ 207 208Musca-S1 has a built-in RGB LED connected to GPIO[4:2] pins. 209 210- Red LED connected at GPIO[2] pin,with optional PWM0. 211- Green LED connected at GPIO[3] pin,with optional PWM1. 212- Blue LED connected at GPIO[4] pin,with optional PWM2. 213 214.. note:: The SCC registers select the functions of pins GPIO[4:2]. 215 216System Clock 217============ 218 219V2M Musca-S1 has a 32.768kHz crystal clock. The clock goes to a PLL and is 220multiplied to drive the Cortex-M33 processors and SSE-200 subsystem. The 221default is 50MHz but can be increased to 200MHz maximum for the secondary 222processor (CPU1) via software configuration. The maximum clock frequency 223for the primary processor (CPU0) is 50MHz. 224 225Serial Port 226=========== 227 228The ARM Musca-S1 processor has two UARTs. Both the UARTs have only two wires 229for RX/TX and no flow control (CTS/RTS) or FIFO. The Zephyr console output, 230by default, uses UART1. 231 232Security components 233=================== 234 235- Implementation Defined Attribution Unit (`IDAU`_). The IDAU is used to define 236 secure and non-secure memory maps. By default, all of the memory space is 237 defined to be secure accessible only. 238- Secure and Non-secure peripherals via the Peripheral Protection Controller 239 (PPC). Peripherals can be assigned as secure or non-secure accessible. 240- Secure boot. 241- Secure `AMBA®`_ interconnect. 242 243Serial Configuration Controller (SCC) 244===================================== 245 246The ARM Musca-S1 test chip implements a Serial Configuration Control (SCC) 247register. The purpose of this register is to allow individual control of 248clocks, reset-signals and interrupts to peripherals, and pin-muxing. 249 250Boot memory 251================ 252Normal Musca-S1 test chip boot operation is from 2MB eMRAM by default, and 253it offers the fastest boot method. Musca-S1 test chip also support to boot from 25432MB off-chip QSPI flash. You can update the DAPLink firmware and set the boot 255selector slider switch for either QSPI or eMRAM for booting. 256 257Programming and Debugging 258************************* 259 260Musca-S1 supports the v8m security extension, and by default boots to the 261secure state. 262 263When building a secure/non-secure application, the secure application will 264have to set the IDAU/SAU and MPC configuration to permit access from the 265non-secure application before jumping. 266 267The following system components are required to be properly configured during 268the secure firmware: 269 270- AHB5 TrustZone Memory Protection Controller (MPC). 271- AHB5 TrustZone Peripheral Protection Controller (PPC). 272- Implementation-Defined Attribution Unit (IDAU). 273 274For more details please refer to `Corelink SSE-200 Subsystem`_. 275 276Flashing 277======== 278 279DAPLink 280--------- 281 282V2M Musca-S1 provides: 283 284- A USB connection to the host computer, which exposes a Mass Storage and an 285 USB Serial Port. 286- A Serial Flash device, which implements the USB flash disk file storage. 287- A physical UART connection which is relayed over interface USB Serial port. 288 289This interfaces are exposed via DAPLink which provides: 290 291- Serial Wire Debug (SWD). 292- USB Mass Storage Device (USBMSD). 293- UART. 294- Remote reset. 295 296For more details please refer 297to the `DAPLink Website`_. 298 299 300Building a secure only application 301---------------------------------- 302 303You can build applications in the usual way. Here is an example for 304the :ref:`hello_world` application. 305 306.. zephyr-app-commands:: 307 :zephyr-app: samples/hello_world 308 :board: v2m_musca_s1 309 :goals: build 310 311Open a serial terminal (minicom, putty, etc.) with the following settings: 312 313- Speed: 115200 314- Data: 8 bits 315- Parity: None 316- Stop bits: 1 317 318Uploading an application to V2M Musca-S1 319---------------------------------------- 320 321To upload the :ref:`hello_world` application to the board, no extra steps are 322required. You can directly upload ``build/zephyr/zephyr.hex``, which is 323generated by Zephyr's build system. 324 325In other situations, applications must first be converted to Intel's hex 326format before being flashed to a V2M Musca-S1. An optional bootloader can also 327be prepended to the image. 328 329The eMRAM base address alias is ``0xA000000``, and the QSPI flash base address 330alias is ``0x0``. The image offset is calculated by adding the flash offset to the 331bootloader partition size (when there is one). 332 333A third-party tool (srecord) can be used to concatenate the images and generate 334the Intel formatted hex image. 335 336For more information refer to the `Srecord Manual`_. 337 338.. code-block:: bash 339 340 srec_cat $BIN_BOOTLOADER -Binary -offset $FLASH_OFFSET $BIN_APP -Binary -offset $IMAGE_OFFSET -o zephyr.hex -Intel 341 342 # For a 128K bootloader IMAGE_OFFSET = $FLASH_OFFSET + 0x20000 343 srec_cat $BIN_BOOTLOADER -Binary -offset 0xA000000 $BIN_APP -Binary -offset 0xA020000 -o zephyr.hex -Intel 344 345.. image:: img/v2m_musca_s1_powered.jpg 346 :align: center 347 :alt: The Musca-S1 with the USB connected and powered-on 348 349To upload the application, connect the V2M Musca-S1 to your host computer using 350the USB port and power-on the board by pressing the PBON button as seen on the 351picture above. The 3 LEDs should be lit (PWR, ON and 5VON) and you should see a 352USB connection exposing a Mass Storage (MUSCA_S) and a USB Serial Port. 353Now copy the generated ``zephyr.hex`` to the MUSCA_S drive. 354 355Reset the board, and if you were building the hello_world application you should 356see the following message on the corresponding serial port: 357 358.. code-block:: console 359 360 Musca-S1 Dual Firmware Version 1.9 361 *** Booting Zephyr OS build zephyr-v2.4.0-2314-gadc81d188323 *** 362 Hello World! musca_s1 363 364Building a secure/non-secure image with Trusted Firmware-M 365---------------------------------------------------------- 366 367The process requires five steps: 368 3691. Build Trusted Firmware-M (TF-M). 3702. Import it as a library to the Zephyr source folder. 3713. Build Zephyr with a non-secure configuration. 3724. Merge the two binaries together and sign them. 3735. Concatenate the bootloader with the signed image blob. 374 375In order to build tfm please refer to `Trusted Firmware-M Guide`_. 376Follow the build steps for AN521 target while replacing the platform with 377``-DTFM_PLATFORM=musca_s1`` and compiler (if required) with 378``-DTFM_TOOLCHAIN_FILE=toolchain_GNUARM.cmake``. 379 380Copy over TF-M as a library to the Zephyr project source and create a shortcut 381for the secure veneers and necessary header files. All files are in the install 382folder after TF-M built. 383 384Building the TF-M integration sample for Musca-S1 385------------------------------------------------- 386 387The TF-M integration samples can be run using the ``v2m_musca_s1_ns`` 388target. Please make sure all the requirements listed in the sample's 389description are met before building. 390 391.. zephyr-app-commands:: 392 :zephyr-app: samples/tfm_integration/psa_crypto 393 :board: v2m_musca_s1_ns 394 :goals: build 395 396To upload the build artifact to the board, first connect the Musca-S1 to your 397computer using the USB port, press the PBON button, and copy 398the ``build/tfm_zephyr.hex`` file onto the MUSCA_S mass storage device. 399(For a more detailed description of these steps, please read the 'Uploading 400an application to V2M Musca-S1' section.) 401 402Once the file transfer has completed, you may reset the board. 403 404The ``tfm_zephyr.hex`` file was generated by concatenating the signed TF-M and 405Zephyr binaries with the MCUboot image, and converting it to Intel's hex format. 406These steps are all performed automatically by CMake. 407 408For alternative build options and more information, please read the 409corresponding TF-M integration example's README file. 410 411.. _V2M Musca-S1 Website: 412 https://developer.arm.com/Tools%20and%20Software/Musca-S1%20Test%20Chip%20Board 413 414.. _Musca-S1 Technical Reference Manual (TRM): 415 https://developer.arm.com/documentation/101835/latest 416 417.. _DAPLink Website: 418 https://github.com/ARMmbed/DAPLink 419 420.. _Cortex-M33 Generic User Guide: 421 https://developer.arm.com/documentation/100235/latest/ 422 423.. _Trusted Firmware-M Guide: 424 https://tf-m-user-guide.trustedfirmware.org/building/tfm_build_instruction.html 425 426.. _Corelink SSE-200 Subsystem: 427 https://developer.arm.com/documentation/dto0051/latest/subsystem-overview/about-the-sse-200 428 429.. _Srecord Manual: 430 https://srecord.sourceforge.net/man/man1/srec_cat.1.html 431 432.. _IDAU: 433 https://developer.arm.com/documentation/100690/latest/Attribution-units--SAU-and-IDAU- 434 435.. _AMBA®: 436 https://developer.arm.com/architectures/system-architectures/amba 437
