\mainpage

Table of Contents

• About the Project
• The Grand Design
  • Block Diagram
  • Memory Map
  • Design Notes
  • Module Status
  • To Do List, Wishlist and Issues
• Rules, Conventions, and Guidelines
• Instructions for Building
• About THIS document and Markdown

Important notes

Status

The current state of this project is Alpha! In other words, there are lots of potholes and several places I have intentions to do some rather major fixups. Notably, I will be refactoring the TLM-2.0 implementation to reflect a much simpler way of including bus interfacing for both the Initiator and Target. This project is being released now because it has been too long since I've updated it.

Contributing

If you have an interest in actively contributing to this project, please contact me directly. There are plenty of modules that need to be developed. A primary and important aspect of this project is to maintain the

About the Platform Project

Back to Table of Contents

This directory contains a basic SystemC design using TLM-2.0 with a single top-level module and a practical main implementation that validates each step, and provides an execution summary including timing/performance information. If errors are detected, main exists with a non-zero status.

This project has several goals:

1. Provide an example of a complete TLM-2 virtual platform for study using Modern C++.
2. Should be able to demonstrate Blinky and Hello-world tests.
3. Provide examples of different techniques of modeling.
4. Loosely-timed and Approximately-timed models of initiators, interconnect and targets
5. The absence of real clocks using the no_clock channel and the global distribution mechanism
6. Resets and Power domain modeling
7. Processor implementation with an ISS and support for interrupts
8. Provide the basis for "Easier SystemC" templates.
9. Several approaches to configuration

At any point in time, this project represents a set of ideas in the making, and not expected to be complete. Various authors may contribute to this effort, and as such, coding guidelines have bee provided here-in. It is important that this code be model code and meet high levels of documentation and formatting to make it easy to understand. Comment blocks are highly encouraged.

Definition: Modern C++ means use of features introduced in the C++ standards from 2011, 2014 and 2017. Of course, we do not mean to be completely indiscriminate in this. Features should be used when they provide some advantage. Any one of the following may be deemed an advantage.

1. Simplify the code and make it easier to understand
2. Provide coding safety against mistakes
3. Improve performance or functionality

Of course there may occasionally be some disagreement in which case there should proceed some discussion and perhaps even more comments in the code to help the reader.

The Grand Design

Block Diagram

Back to Table of Contents

• Names inside the boxes are instance names.
• Names outside the boxes are part of a module name.
• Blocks with an exclamation mark (!), either generate or receive interrupts.
• Dotted boxes indicate a power or reset domain

Top
+------------------------------------------------------------------+
|                                                                  |
|    SystemMgr            Mcu                                      |
|     +-----+             +-----+   +-----+                        |
|     | sys |             |mcu2 >---> mbx >------.                 |
|     +-----+             +-----+   +-----+      |                 |
| Mcu                                            |                 |
| +----------------------------------------------^---------------+ |
| |......................                        |             r0| |
| |:  Cpu   r1: Dma   r2: Pic       Gpio         |     Crypto    | |
| |:  +-----+ : +-----+ : +-----+   +-----+      |     +-----+   | |
| |:  ! cpu ! : | dma ! : ! pic !   | gio !      x----->crypt!   | |
| |:  +--v-v+ : +v-^-v+ : +--^--+   +--^--+      |     +-----+   | |
| |:     | |  :..|.|.|..:    |         |         |               | |
| |:     | |  :  | | |       |         |         |               | |
| |:     |<|-----' '-x-------x---------x---------x     SBus      | |
| |:     | |  :              |         |         |     +-----+   | |
| |:  Mmu| '------.          |         |         x-----> spi !   | |
| |:  +--v--+ :+--v--+    +--v--+   +--v--+      |     +--v--+   | |
| |:  ! mmu ! :| tcm |    | ssd |   |flash|      |        |      | |
| |:  +v---v+ :+-----+    +-----+   +-----+     S|   .----'      | |
| |:  P|  S|  :Memory     Ssd       Flash       o|   | Environ   | |
| |:   |   |  :                                 u|   | +-----+   | |
| |:.--'   |  ...............................   t|   x-> env |   | |
| |:| Cache|  : Ssd   r4: Mouse r5: Keybd r6:   h|   | +-----+   | |
| |:| +----v+ : +-----+ : +-----+ : +-----+ :    |   |           | |
| |:| | l2c | : | thb | : | ptr | : | kbd | :   B|   | +-----+   | |
| |:| +--v--+ : +--^--+ : +--^--+ : +--^--+ :   u|   '-> gps |   | |
| |:|    |    :....|....:....|....:....|....:   s|     +-----+   | |
| |:'--->|    :    '---------x---------'         |     Gps       | |
| |:.....|....:              |                   |               | |
| |   Bus|      Disk      Usb|      Bus          |     Memory    | |
| |   +--V--+   +-----+   +--^--+   +-----+      |     +-----+   | |
| |   | nth |   | dsk !   | usb !   | sth >------x-----> ddr |   | |
| |   +--V--+   +--^--+   +--^--+   +--^--+      |     +-----+   | |
| |      |         |         |         |         |               | |
| |      x---------x---------x---------x         x--------.      | |
| |      |         |         |         |         |        |      | |
| |      |         |    .....|.........|.....    |        |      | |
| |      |         |    :    |         |  r3:    |        |      | |
| |   +--v--+   +--v--+ : +--v--+   +--v--+ : +--v--+  +--v--+   | |
| |   | ram |   | rom | : | net !   | vid ! : | tmr !  | ser !   | |
| |   +-----+   +-----+ : +-----+   +-----+ : +-----+  +-----+   | |
| |   Memory    Memory  : Wifi      Video   : Timer    Uart      | |
| |                     :...................:                    | |
| |                                                              | |
| +--------------------------------------------------------------+ |
+------------------------------------------------------------------+

Memory Map

Back to Table of Contents

Design Notes

Back to Table of Contents

• Main buses are designated as North (nth), and South (sth)
• North bus is closest to the "main" processor (cpu)
• System clock 400MHz
• Processor is RISC (cm0+ or possibly w/ FPU e.g. Arm cm4f)
• Cpu tasks provide initiator behaviors (e.g. memory test, processor emulation)
• NTH is 32 bits 100MHz
• STH is 16 bits 50MHz
• rom is a type flash (fast write)
• flash is paged slower flash with separate controls
• Gpio has 64 pins and can additionally be stimulated or record from/to files
• Terminal communicates via TCP sockets
• Video reads/writes files
• Wifi sends/receives from web
• Timer is expandable (1-16)
• Memory has read-only option & supports DMI
• Mmu has zero latency
• DiskCtrl reads/writes real files
• Dma has configurable # channels (1-16)
• Pic accepts N sources, simple priority interrupt controller
• Serial I/O configurable baud
• Eventually Video or Wifi may become a hierarchical sub-system
• Eventually one of the buses will become customized
• Order of development is TBD, but simplest first
• Four power regions labeled r0 through r6
• One hierarchical boundary in the Proc_module represented by r1
• SystemManager manages clocks/power/resets

Module Status

Back to Table of Contents

Each module will its status noted here. The following states are allowed:

• Thought - placeholder from this document not yet tackled
• Concept - documentation has begun
• Started - initial coding (some files in various states)
• Basic - basic functionality achieved with minimal coding
• Tested - extensive testing completed

To Do List

Back to Table of Contents

In order of priority:

1. Abstract TLM connetivity into protocol specific submodules with simpler API
   1. Base_protocol
   2. APB_protocol
   3. AXI_protocol
2. Finish pic_api.h and add pic_test.cpp.
3. Add gpio_api.h and add gpio_test.cpp.
4. Finish Uart_module
5. Add Dma_module
6. Add dma_api.h and dma_test.cpp
7. Add power-down capability (?use CCI?) with reset
8. Add timing to AT mode of Bus_module with analysis port support
9. Implement filter interconnect
10. Implement a CPU emulation (e.g. armv6m or Mini32)
11. Modify configuration to support CCI parameters
12. Update licensing/copyright info (Doulos Inc.)
13. Update doxygen
14. Add static checking (?cccc)

Optional

1. Add fancy report handler with XML option and expectations for error injection
2. Consider refactor Cpu_module to use PIMPL and separate API and tests.
3. Consider refactor Memory_module to use PIMPL
4. Add a shell interface and a scripting language for use in a CPU thread. LUA, Python or TCL.
5. Add a Stack_module (LIFO).
6. Add Global class to replace g_ variables and provide better control/observation. Or use CCI.
7. Apb2tlm_adapter and Tlm2apb_adapter
8. Axi2tlm_adapter and Tlm2axi_adapter

Issues and ideas

Add liberally here if you have contribution permissions; otherwise, use GitHub issues.

• More collaborators might be good
• Testing needs to go deeper
• Stronger emphasis on the <AS-IS> state of the project.

See Also

• Related project https://github.com/dcblack/sc-templates

Rules, Conventions, and Guidelines

Back to Table of Contents

• Documentation will be maintained in GitHub style Markdown
  • ABOUT_{:NAME:}.md will document each module
• C++14 standard will be the minimum C++ standard level used.
• Header filenames have suffix .hpp unless purely C11 compatible.
• Compiled C++ filenames have suffix .cpp unless purely C11 compatible.
• Raw pointers and arrays will be avoided. Instead use std::unique_ptr<>, std::shared_ptr<>, std::vector<>, etc. when possible. References are better than pointers of any type.
• cstdint will be preferred over built-in types.
• Destructors will be defined. default is allowed if no allocations need to be managed.
• TLM Base Protocol will be preferred.
• Ignorable extensions will be preferred.
• Underscores will be used to separate words.
• User-defined types (e.g. classes, structs, enums) will start. with use Name case.
• enum class will be preferred over simple enum
• Methods and variables will be lowercase.
• UPPERCASE may be used for labels, enumeration values and constants only.
• and will be preferred over &&.
• or will be preferred over ||.
• not will be preferred over !.
• Leading or trailing underscores \_ will NEVER be used together (i.e. a_ and _a are legal, but _a_ is not).

Extras

Numerous extras have been added including:

• report.h is provided to simplify message reporting. See report.h comments for more information.
• configuration.h and config/configuration.cpp provide a generalized configuration mechanism that used to configure memory maps and other features.
• proxy.h and proxy.cpp supply a proxy for modules that do not have Configuration built in.

Instructions for Building

Back to Table of Contents

Dependencies

• Cmake is used to configure.
• SystemC version 2.3.2 or better
• C++14 or better
• Boost libraries

If you would like to contribute, you should also have:

• git
• astyle

Linux/OSX

1. Open a terminal and navigate into the build/ directory located where this file is located.
2. Configure by typing cmake ..
3. Build code with make or make all
4. Alternately, build and run with make run
5. To pass arguments to run, use env ARGS="-your args" make run
6. To cleanup after running, use make clean A slightly more automated approach uses some scripts located in the bin/ directory. A setup.profile bash script should be sourced to set environment variables; however, it will need some tweaking. For one thing, it uses modulecmd to setup C++ (clang), SystemC and Boost environment.

Windows

To be determined

About Markdown

Back to Table of Contents

This document is maintained with the rest of the project on GitHub at https://github.com/dcblack/sc-platform.

Tip: If you are reading this document in VIM (or any variant) text, you will notice unique labels in this document. For instance, this section starts an HTML anchor with an attribute value inside double quotes. If you are in Vim (vi or gvim too), you can place the cursor on the word and press asterisk *, which will take you to the table of contents. Another press will bring you back. So you can quickly navigate anywhere from the table of contents! :-)

This document was created as a MarkDown text file.

• Best viewed with a Markdown rendering tool (e.g. Typora, ReText or Atom).
• Or generate HTML, PDF or DOC using pandoc http://pandoc.org/installing.html
• Do not edit derived files
• For apps that view/edit markdown see https://github.com/karthik/markdown_science/wiki/Tools-to-support-your-markdown-authoring.
• Same syntax as used for GitHub README's etc. Very popular among programmers.

Reasons for GitHub Markdown include:

• Very simple - relatively intuitive and easy to learn
• No special tools - works for any text editor across platforms (Linux, Windows, Mac, iPhone)
• Supports code syntax highlighting
• Easy to integrate into web-pages
• Easy to convert to Word, PDF, Pod, Tex, HTML
• Wide spread support in the programming community
• Small files
• VERY portable

The end