@micro-os-plus/architecture-riscv 4.1.0

package/CHANGELOG.md

@@ -0,0 +1,152 @@
+# Change & release log
+
+Releases in reverse chronological order.
+
+Please check
+[GitHub](https://github.com/micro-os-plus/architecture-riscv-xpack/issues/)
+and close existing issues and pull requests.
+
+## 2022-07-28
+
+* v4.1.0
+* e19aa16 #5: remove linker script ARM sections
+* 5f43150 #7: add sections-flash.ld
+* 963be52 #6: rework semihosting_call_host() to avoid asm() registers
+* 31ebece #4: add signed_register_t for semihosting result
+
+## 2022-07-25
+
+* 0f03dd3 add preliminary xpack.json
+
+## 2022-07-24
+
+* v4.0.0
+
+## 2022-07-21
+
+* move rtos out
+
+## 2021-03-10
+
+* v3.0.2
+* gitkeep device/include
+* v3.0.1
+* fix/silence warnings
+
+## 2021-03-09
+
+* v3.0.0
+* separate rtos-port folder
+* fix/silence warnings
+
+## 2021-03-01
+
+* v2.0.0
+
+## 2021-02-28
+
+* rename micro_os_plus
+
+## 2021-02-04
+
+* v1.1.0
+* first restructured release
+
+## 2020-09-19
+
+* v1.0.3
+* bump startup to 1.0.8
+
+## 2018-04-16
+
+* v1.0.2
+* bump deps & move back to npm
+* update README developer info
+
+## 2018-01-24
+
+* v1.0.1
+* update dependencies
+
+## 2018-01-24
+
+* v1.0.0
+
+### 2018-01-20
+
+* [#271] Reimplement RISC-V semihosting
+* semihosting asm: remove "cc"
+
+### 2018-01-15
+
+* [#2] Use wfi() in infinite loops
+* [#3] Add semihosting call_host() implementation
+
+##  (2018-01-09)
+
+* v0.2.0
+
+## 2017-11-10
+
+* README: reformat prerequisites
+* arch-functions.cpp: fix typo
+* README: explain xpm install
+* README: refer to CHANGELOG in message
+* README: update license with links
+* do not ignore package-lock
+
+## 2017-11-07
+
+* traps.cpp: add `handle_machine_ext()` declaration
+* ignore package-lock for now
+* rework interrupts to use namespaces
+
+## 2017-10-30
+
+* arch-defines: fix `MCAUSE_CAUSE` for 32-bits
+* traps.cpp: fix section `.traps_handlers`
+* reset-entry.S: cosmetise comments
+
+## 2017-10-29
+
+* include/\*: rename csr set/clear_\*_bits
+* include/\*/defines.h: simplify & prefix
+* include/\*/types.h: add exc & irq enums
+* include/platform-functions-inlines.h added
+* src/traps.cpp: rename `riscv_interrupts_local_handlers`
+* include/core-functions.h: move `riscv_trap_entry()` here
+* include/\*: update guard macros
+
+## 2017-10-28
+
+* src/traps.cpp: move local handlers to device
+* include/architecture-riscv/defines.h: number of exc
+* update for device-peripherals.h
+
+## 2017-10-26
+
+* v1.1.0
+* update for new GitHub names
+
+## 2017-10-04
+
+* v0.0.4
+* package.json clean-ups
+* add CHANGELOG.md
+
+## 2017-09-18
+
+* v0.0.3
+* add enable/disable M external interrupts
+* add plic-functions.h
+* traps.cpp: use new plic api
+* csr-functions*.h: add `mhartid()`
+* `*_exception_`, `*_interrupt_local_`
+  - for improved readability, use full names
+  - use local_device array, if needed
+
+## 2017-09-04
+
+* v0.0.2
+* v0.0.1
+* initial version, copied from µOS++.

package/CMakeLists.txt

@@ -0,0 +1,87 @@
+# -----------------------------------------------------------------------------
+#
+# This file is part of the µOS++ distribution.
+#   (https://github.com/micro-os-plus/)
+# Copyright (c) 2021 Liviu Ionescu
+#
+# Permission to use, copy, modify, and/or distribute this software
+# for any purpose is hereby granted, under the terms of the MIT license.
+#
+# If a copy of the license was not distributed with this file, it can
+# be obtained from https://opensource.org/licenses/MIT/.
+#
+# -----------------------------------------------------------------------------
+
+# This file is intended to be consumed by applications with:
+#
+# `add_subdirectory("xpacks/micro-os-plus-architecture-riscv")`
+#
+# The result is an interface library that can be added to the linker with:
+#
+# `target_link_libraries(your-target PUBLIC micro-os-plus::architecture-riscv)`
+
+# -----------------------------------------------------------------------------
+## Preamble ##
+
+# https://cmake.org/cmake/help/v3.20/
+cmake_minimum_required(VERSION 3.20)
+
+project(
+  micro-os-plus-architecture-riscv
+  DESCRIPTION "µOS++ RISC-V architecture"
+)
+
+if(COMMAND xpack_get_package_name_and_version)
+  xpack_get_package_name_and_version("${CMAKE_CURRENT_SOURCE_DIR}/package.json")
+  message(VERBOSE "Processing xPack ${PACKAGE_JSON_NAME}@${PACKAGE_JSON_VERSION}...")
+endif()
+
+# -----------------------------------------------------------------------------
+## The project library definitions ##
+
+# https://cmake.org/cmake/help/v3.20/command/add_library.html?highlight=interface#normal-libraries
+# PRIVATE: build definitions, used internally
+# INTERFACE: usage definitions, passed up to targets linking to it
+# PUBLIC: both
+
+add_library(micro-os-plus-architecture-riscv-interface INTERFACE EXCLUDE_FROM_ALL)
+
+# -----------------------------------------------------------------------------
+# Target settings.
+
+target_include_directories(micro-os-plus-architecture-riscv-interface INTERFACE
+  "include"
+)
+
+target_sources(micro-os-plus-architecture-riscv-interface INTERFACE
+  # None.
+)
+
+target_compile_definitions(micro-os-plus-architecture-riscv-interface INTERFACE
+  # None.
+)
+
+target_compile_options(micro-os-plus-architecture-riscv-interface INTERFACE
+  # None.
+)
+
+target_link_libraries(micro-os-plus-architecture-riscv-interface INTERFACE
+  # Dependencies
+  # None.
+)
+
+if (COMMAND xpack_display_target_lists)
+  xpack_display_target_lists(micro-os-plus-architecture-riscv-interface)
+endif()
+
+# -----------------------------------------------------------------------------
+# Aliases.
+
+# https://cmake.org/cmake/help/v3.20/command/add_library.html#alias-libraries
+add_library(micro-os-plus::architecture-riscv ALIAS micro-os-plus-architecture-riscv-interface)
+message(VERBOSE "> micro-os-plus::architecture-riscv -> micro-os-plus-architecture-riscv-interface")
+
+add_library(micro-os-plus::architecture ALIAS micro-os-plus-architecture-riscv-interface)
+message(VERBOSE "> micro-os-plus::architecture -> micro-os-plus-architecture-riscv-interface")
+
+# -----------------------------------------------------------------------------

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Liviu Ionescu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,317 @@
+[![license](https://img.shields.io/github/license/micro-os-plus/architecture-riscv-xpack)](https://github.com/micro-os-plus/architecture-riscv-xpack/blob/xpack/LICENSE)
+[![CI on Push](https://github.com/micro-os-plus/architecture-riscv-xpack/actions/workflows/CI.yml/badge.svg)](https://github.com/micro-os-plus/architecture-riscv-xpack/actions/workflows/CI.yml)
+
+# A source library xPack with the µOS++ RISC-V architecture definitions
+
+This project provides the **architecture-riscv** source library as an xPack
+dependency and includes architecture definitions for RISC-V embedded projects.
+
+The project is hosted on GitHub as
+[micro-os-plus/architecture-riscv-xpack](https://github.com/micro-os-plus/architecture-riscv-xpack).
+
+## Maintainer info
+
+This page is addressed to developers who plan to include this source
+library into their own projects.
+
+For maintainer info, please see the
+[README-MAINTAINER](README-MAINTAINER.md) file.
+
+## Install
+
+As a source library xPack, the easiest way to add it to a project is via
+**xpm**, but it can also be used as any Git project, for example as a submodule.
+
+### Prerequisites
+
+A recent [xpm](https://xpack.github.io/xpm/),
+which is a portable [Node.js](https://nodejs.org/) command line application.
+
+For details please follow the instructions in the
+[xPack install](https://xpack.github.io/install/) page.
+
+### xpm
+
+This package is available from npmjs.com as
+[`@micro-os-plus/architecture-riscv`](https://www.npmjs.com/package/@micro-os-plus/architecture-riscv)
+from the `npmjs.com` registry:
+
+```sh
+cd my-project
+xpm init # Unless a package.json is already present
+
+xpm install @micro-os-plus/architecture-riscv@latest
+
+ls -l xpacks/micro-os-plus-architecture-riscv
+```
+
+### Git submodule
+
+If, for any reason, **xpm** is not available, the next recommended
+solution is to link it as a Git submodule below an `xpacks` folder.
+
+```sh
+cd my-project
+git init # Unless already a Git project
+mkdir -p xpacks
+
+git submodule add https://github.com/micro-os-plus/architecture-riscv-xpack.git \
+  xpacks/micro-os-plus-architecture-riscv
+```
+
+## Branches
+
+Apart from the unused `master` branch, there are two active branches:
+
+- `xpack`, with the latest stable version (default)
+- `xpack-develop`, with the current development version
+
+All development is done in the `xpack-develop` branch, and contributions via
+Pull Requests should be directed to this branch.
+
+When new releases are published, the `xpack-develop` branch is merged
+into `xpack`.
+
+## Developer info
+
+### Overview
+
+This source xPack provides general RISC-V definitions and will eventually
+include the implementation for a hardware abstraction layer, which,
+for RISC-V is not yet standardized.
+
+### Status
+
+The **architecture-riscv** source library is fully functional,
+but minimalistic, for running semihosted tests.
+
+### Design details
+
+From a top down approach, in µOS++, the RISC-V definitions are
+grouped by several criteria:
+
+- platform (board)
+- device
+- core
+- hart (hardware thread)
+
+#### Platform
+
+The platform level refers to a device and adds platform specific definitions,
+like what GPIO pins are used for various LEDs, buttons, etc.
+
+The portable way to include platform specific definitions in an application is:
+
+```c
+#include <micro-os-plus/platform.h>
+```
+
+In µOS++, the platform specific definitions are grouped in the
+`riscv::platform` namespace.
+
+An example of a platform package is **sifive/platform-sifive-hifive1** with the
+SiFive HiFive1 small development board.
+
+#### Device
+
+The RISC-V documentation introduces the term _platform_ as:
+
+> A RISC-V hardware _platform_ can contain one or more RISC-V-compatible
+processing cores together with other non-RISC-V-compatible cores,
+fixed-function accelerators, various physical memory structures,
+I/O devices, and an interconnect structure to allow the components
+to communicate.
+
+In modern implementations, this is generally either a physical chip
+or a synthesised one.
+
+In other contexts, _platform_ has a broader meaning and may refer to
+the environment in which a piece of software is executed; it may be
+the hardware or the operating system (OS); to avoid confusions, in
+µOS++ the term **device** is used to identify the vendor specific
+RISC-V details (with _platform_ being used for the machine, or the board).
+
+Please note that RISC-V defines some common MMIO registers (like
+`mtime` and `mtimecmp`), but, for more flexibility, leaves the
+implementation to define the actual address. Unfortunately this
+increases the software complexity, since the device specific headers
+must define some fixed symbols and the header files must be included
+in a careful order, to avoid circular references.
+
+In µOS++, the device specific definitions are grouped in the
+`riscv::device` namespace.
+
+The portable way to include device specific definitions in an application is:
+
+```c
+#include <micro-os-plus/device.h>
+```
+
+Example of device packages are **sifive/devices** with the SiFive
+Freedom E310 and E31/E51 Arty devices.
+
+#### Core
+
+The RISC-V documentation introduces the term _core_ as:
+
+> A component is termed a core if it contains an independent
+instruction fetch unit. A RISC-V-compatible core might support
+multiple RISC-V-compatible hardware threads, or harts, through
+multi-threading.
+
+In µOS++, the core specific definitions are grouped in the
+`riscv::core` namespace.
+
+The portable way to include architecture specific definitions
+in an application is:
+
+```c
+#include <micro-os-plus/architecture.h>
+```
+
+#### Hart
+
+Hardware threads are the working horses of the software threads;
+each hardware thread has its own set of general registers and
+Control and Status Registers (CSRs); the OS may schedule a
+maximum number of software threads equal with the number of
+hardware threads, possibly with some grouping constrains.
+
+In RISC-V, **Control and Status Registers** (**CSR**s) are
+a special group of registers, available via specific `csr`
+instructions from a separate addressing space not visible in
+the memory space.
+
+The `hart` specific definitions are grouped under the `riscv::csr` namespace.
+
+#### Other namespaces
+
+Interrupts and exceptions are grouped under `riscv::irq` and `riscv::exc`.
+
+### Build & integration info
+
+The project is written in C++ and assembly and it is expected
+to be used in C and C++ projects.
+
+The source code was compiled with riscv-none-elf-gcc 12,
+and should be warning free.
+
+To ease the integration of this package into user projects, there
+are already made CMake and meson configuration files (see below).
+
+For other build systems, consider the following details:
+
+#### Include folders
+
+The following folders should be passed to the compiler during the build:
+
+- `include`
+
+The header files to be included in user projects are:
+
+```c++
+#include <micro-os-plus/architecture.h>
+```
+
+#### Source files
+
+The source files to be added to user projects are:
+
+- none
+
+#### Preprocessor definitions
+
+- none
+
+#### Compiler options
+
+- `-std=c++20` or higher for C++ sources
+- `-std=c11` for C sources
+
+#### C++ Namespaces
+
+- `micro_os_plus::architecture`
+
+#### C++ Classes
+
+TBD
+
+#### Dependencies
+
+- none
+
+#### CMake
+
+To integrate the architecture-riscv source library into a CMake application,
+add this folder to the build:
+
+```cmake
+add_subdirectory("xpacks/micro-os-plus-architecture-riscv")`
+```
+
+The result is an interface library that can be added as an application
+dependency with:
+
+```cmake
+target_link_libraries(your-target PRIVATE
+
+  micro-os-plus::architecture-riscv
+)
+```
+
+#### meson
+
+To integrate the architecture-riscv source library into a meson application,
+add this folder to the build:
+
+```meson
+subdir('xpacks/micro-os-plus-architecture-riscv')
+```
+
+The result is a dependency object that can be added
+to an application with:
+
+```meson
+exe = executable(
+  your-target,
+  link_with: [
+    # Nothing, not static.
+  ],
+  dependencies: [
+    micro_os_plus_architecture_riscv_dependency,
+  ]
+)
+```
+
+### Examples
+
+TBD
+
+### Known problems
+
+- none
+
+### Tests
+
+TBD
+
+## Change log - incompatible changes
+
+According to [semver](https://semver.org) rules:
+
+> Major version X (X.y.z | X > 0) MUST be incremented if any
+backwards incompatible changes are introduced to the public API.
+
+The incompatible changes, in reverse chronological order,
+are:
+
+- v4.x: move rtos-port outside
+- v3.x: move rtos-port to separate folder
+- v2.x: rename micro_os_plus
+
+## License
+
+The original content is released under the
+[MIT License](https://opensource.org/licenses/MIT/),
+with all rights reserved to
+[Liviu Ionescu](https://github.com/ilg-ul/).

package/include/micro-os-plus/architecture-riscv/core-functions-inlines.h

@@ -0,0 +1,86 @@
+/*
+ * This file is part of the µOS++ distribution.
+ *   (https://github.com/micro-os-plus/)
+ * Copyright (c) 2017 Liviu Ionescu.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/licenses/MIT/.
+ */
+
+#ifndef MICRO_OS_PLUS_ARCHITECTURE_RISCV_CORE_FUNCTIONS_INLINES_H_
+#define MICRO_OS_PLUS_ARCHITECTURE_RISCV_CORE_FUNCTIONS_INLINES_H_
+
+// ----------------------------------------------------------------------------
+
+#include <stdint.h>
+
+// ----------------------------------------------------------------------------
+// Inline implementations for the RISC-V core support functions.
+
+#if defined(__cplusplus)
+extern "C"
+{
+#endif // defined(__cplusplus)
+
+  // --------------------------------------------------------------------------
+
+  static inline __attribute__ ((always_inline)) void
+  riscv_core_enable_machine_external_interrupts (void)
+  {
+    riscv_csr_set_mie_bits (RISCV_CSR_MIP_MEIP);
+  }
+
+  /**
+   * @brief Disable external interrupts (used by PLIC).
+   */
+  static inline __attribute__ ((always_inline)) void
+  riscv_core_disable_machine_external_interrupts (void)
+  {
+    riscv_csr_clear_mie_bits (RISCV_CSR_MIP_MEIP);
+  }
+
+  // --------------------------------------------------------------------------
+
+#if defined(__cplusplus)
+}
+#endif // defined(__cplusplus)
+
+// ============================================================================
+
+#if defined(__cplusplus)
+
+// ----------------------------------------------------------------------------
+
+namespace riscv
+{
+  namespace core
+  {
+
+    inline __attribute__ ((always_inline)) void
+    enable_machine_external_interrupts (void)
+    {
+      riscv_core_enable_machine_external_interrupts ();
+    }
+
+    inline __attribute__ ((always_inline)) void
+    disable_machine_external_interrupts (void)
+    {
+      riscv_core_disable_machine_external_interrupts ();
+    }
+
+    // ------------------------------------------------------------------------
+  } // namespace core
+} // namespace riscv
+
+// ----------------------------------------------------------------------------
+
+#endif // defined(__cplusplus)
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_OS_PLUS_ARCHITECTURE_RISCV_CORE_FUNCTIONS_INLINES_H_
+
+// ----------------------------------------------------------------------------