adding cookbook for RISC-V golden model

cookbook/doc/Makefile

@@ -0,0 +1,80 @@
+# vim: set tabstop=4 shiftwidth=4 noexpandtab
+# ================================================================
+# Filename:		Makefile
+#
+# Description:	Makefile for building a complete RISC-V Sail cookbook
+#
+# 				asciidoctor-reducer needs to be installed
+#
+# 				Because github does not handle 'include' directives,
+#				we use asciidoctor-reducer to pull in the various
+#				include files into one adoc file which can be
+#				rendered by github.
+#
+#				NOTE: Some git trickery is needed in order to ensure that
+#				the complete file has been compiled to the latest 
+#				level and then committed.  See the .git/hooks/pre-commit
+#				and .git/hooks/post-commit so see how this is done.
+#
+# Author(s):	Bill McSpadden ([email protected])
+#
+# Revision:		See git logs
+#
+# ================================================================
+
+#==============
+# Includes
+#==============
+
+
+#==============
+# Make variables
+#==============
+
+FINAL_ADOC_TARGET 		:= TheRISCVSailCookbook_Complete.adoc
+TOP_ADOC_FILE			:= TheRISCVSailCookbook_Main.adoc
+FINAL_PDF_TARGET		:= TheRISCVSailCookbook_Complete.pdf
+
+ALL_DEPENDENCIES		:= 
+CODE_SNIPPETS_DIR 		:= ../functional_code_examples
+ALL_DEPENDENCIES		+= 
+
+# hello_world example
+#HELLO_WORLD_DIR 		:= ${CODE_SNIPPETS_DIR}/hello_world
+#HELLO_WORLD_FILES		:= ${HELLO_WORLD_DIR}/hello_world.sail  ${HELLO_WORLD_DIR}/Makefile
+
+ALL_DEPENDENCIES		+= ${HELLO_WORLD_FILES}
+
+
+TMP_ADOC				:= ./tmp.adoc
+
+#==============
+# Targets and rules
+#==============
+all : ${FINAL_ADOC_TARGET} ${FINAL_PDF_TARGET}
+
+echo_final_adoc_target :
+	echo ${FINAL_ADOC_TARGET} ;
+
+
+${FINAL_ADOC_TARGET} : ${TOP_ADOC_FILE} ${ALL_DEPENDENCIES}
+	asciidoctor-reducer $< -o $@ ;
+	rm -f ${TMP_ADOC} ;
+	echo "// =========================================================================" >> ${TMP_ADOC} ;
+	echo "// DO NOT EDIT.  AUTOGENERATED FILE.  You probably want to edit $<"           >> ${TMP_ADOC} ;
+	echo "// =========================================================================" >> ${TMP_ADOC} ;
+	mv $@ $@.tmp ;
+	cat ${TMP_ADOC} $@.tmp > $@ ;
+	rm -f $@.tmp ${TMP_ADOC} ;
+
+${FINAL_PDF_TARGET} : ${FINAL_ADOC_TARGET}
+	asciidoctor-pdf $<
+
+
+.PHONY: clean
+clean:
+	rm -f ${FINAL_ADOC_TARGET} ${FINAL_PDF_TARGET} ${TMP_ADOC} 
+
+
+
+

cookbook/doc/RISCV_model_FAQ.adoc

@@ -0,0 +1,89 @@
+=== Frequently Asked Questions about the Sail RISC-V Golden Model
+
+<<q_is_there_support_for_multi_hart_multi_core_simulation>>
+
+<<q_what_are_ml_files__what_are_their_purpose>>
+
+<<q__is_there_any_support_for_MTIMER>>
+
+<<q__is_the__main_loop__coded_in_Sail>>
+
+<<q-can-gdb-attach-to-the-riscv-golden-model-to-debug-riscv-code>>
+
+<<q__why_two_executables>>
+
+<<q___is_there_support_in_the_model_for_misaligned_memory_accesses>>
+
+<<q-what-is-the-meaning-of-life-the-universe-and-everything>>
+
+<<q-what-does-the-answer-to-what-is-the-meaning-of-life-the-universe-and-everything-mean>>
+
+
+[#q_is_there_support_for_multi_hart_multi_core_simulation]
+==== Q: Is there support for multi-HART or multi-Core simulation?
+
+A: There is no inherent support for multi-HART or multi-Core within the existing RISC-V Sail model. 
+There are future plans for adding this kind of simulation.  It is needed in order to simulate 
+(in a meaningful way) the atomic memory operations and to evaluate memory consistency
+and coherency.
+
+//  ( The following is from email between Bill McSpadden and Martin Berger )
+//  ( Subject: RISC-V Sail model questions, round 1: Multi-core, MTIMER, MMIO, main loop)
+//  ( Date: Feb 15, 2022, 7:20AM)
+
+The model isn't directly about testing. Testing is a separate
+activity. The point of the model is to be as clear as possible. and we
+should keep testing and the model separate.
+
+//  ( The following is from email between Bill McSpadden and Martin Berger )
+//  ( Subject: RISC-V Sail model questions, round 1: Multi-core, MTIMER, MMIO, main loop)
+//  ( Date: Feb 15, 2022, 7:20AM)
+
+[#q_what_are_ml_files__what_are_their_purpose]
+==== Q: What are .ml files?  What are their purpose?
+
+A: These are OCaml files. They are to the ocaml emulator what the .c
+files are to the c emulator. I question the need for an OCaml emulator
+,see also https://github.com/riscv/sail-riscv/issues/138
+
+[#q__is_there_any_support_for_MTIMER]
+==== Q: Is there any support for MTIMER?
+
+A: Yes.  MTIMER functionality lives in riscv_platform.sail.  At this date (2022-05-27) it lives
+at a fixed MMIO space as specified by the MCONFIG CSR.  In the future, once the Golden Model supports
+the RISCV_config YAML structure, the MTIMER can be assigned any address.
+
+[#q__is_the__main_loop__coded_in_Sail]
+==== Q: Is the "main loop" coded in Sail?
+
+A: Yes.  The main execution loop can be found in main.sail.
+
+[#q-can-gdb-attach-to-the-riscv-golden-model-to-debug-riscv-code]
+==== Q: Can gdb attach to the RISCV Golden Model to debug RISCV code?
+
+A:  Not at this time (2022-05-27).  It is being looked at as an enhancement.
+
+[#q__why_two_executables]
+==== Q: There are two C executables built: riscv_sim_RV32 and riscv_sim_RV64. Is there a reason why we need two executables? Can't XLEN be treated as a run-time setting rather than a compile time setting?
+
+A:  (Response from Martin Berger) I think this would require a redesign of the Sail code because of the way Sail's liquid types work. Currently xlen is a global type constant, that is used, directly or indirectly, everywhere. As a type-constant it is used during type checking. The typing system might (note the subjunctive) be flexible enough to turn this into a type-parameter, but probably not without major code surgery. I think we should ask the Cambridge team why they decided on the current approach.
+
+[#q___is_there_support_in_the_model_for_misaligned_memory_accesses]
+==== Q:  Is there support in the model for misaligned memory accesses?
+
+A: (Response from Martin Berger) Short answer: I don't know. Alignment stuff is distributed all over the code base.  riscv_platform.sail has some configuration options for this. Maybe that's a place to start looking?
+
+
+//  ( The following is some sample questions based on HGttG,Hitchhikers Guide to the Galax)
+
+[#q-what-is-the-meaning-of-life-the-universe-and-everything]
+==== Q: What is the meaning of life, the universe and everything?
+
+A: 42
+
+[#q-what-does-the-answer-to-what-is-the-meaning-of-life-the-universe-and-everything-mean]
+==== Q: What does the answer to "What is the meaning of life, the universe and everything" mean?
+
+A: One must construct an experimental, organic computer to compute the meaning.
+Project 'Earth' is one such computer.  Timeframe for an expected answer is... soon.
+

cookbook/doc/TheRISCVSailCookbook_Main.adoc

@@ -0,0 +1,118 @@
+:doctype: book
+:sectids:
+The RISC-V Sail Programming Language: A Cookbook for the RISC-V ISA
+==============================================
+William C. McSpadden <bill@riscv.org>; Martin Berger <contact@martinfriedrichberger.net>
+:toc:
+:toc-placement: preamble
+:toclevels: 2
+
+:showtitle:
+
+
+// Need some preamble to get TOC
+{empty}
+
+
+[#list_of_programming_examples]
+== List of programming examples (in increasing complexity)
+
+The main purpose of this document,  is to give the user a set
+of programming examples for working on the RISC-V Sail model
+(often referred to as the RISC-V Golden Model).  The examples
+will show the user how to change or extend the model.  And it
+will also show the user how to write a RISC-V program (in both 
+assembler and C) and then run it on the Golden Model.
+
+You should read and utilize this document after you have a good
+handle on the Sail programming language. 
+
+<<platform-configuration>>
+
+
+:sectnums:
+== Introduction
+
+
+
+== How to contribute (Bill)
+
+
+=== Coding and indentation style
+
+
+=== Brevity
+
+Program examples should be short, both in terms of number-of-lines and in terms of execution time.  
+Each example should focus on one simple item.  And the execution of the example item should be clear.  
+The example should be short, standalone and easy to maintain.
+
+
+=== Maintainership (when something breaks)
+
+We would also ask that if you contribute a code example,  that you would maintain it.
+
+=== Syntax highlighting for Sail
+
+Syntax highlighting for several editors (emacs, vim, Visual Studio, etc)
+can be found at:
+
+https://github.com/rems-project/sail/tree/sail2/editors
+
+It is beyond the scope of this document to describe how to use
+the syntax highlighting for the various editors.
+
+== Sail installation
+
+TBD
+
+=== Ubuntu (Bill Mc.)
+
+TBD
+
+=== MacOS (Martin)
+
+TBD
+
+=== Docker
+
+Docker is used as a ....
+
+=== Windows 
+
+
+=== Windows: Cygwin (Bill Mc.,  low priority)
+
+
+=== Other?
+
+
+== Basic description
+=== What Sail is
+Sail is a programming language that is targetted for
+ specifying an ISA.  Once specified, a set of
+instructions (usually found in a .elf file) can then
+be executed on the "model" and the results observed.
+
+The model is a sequential model only;  at this time, 
+there are no semantics allowing for any type of parallel
+execution.  
+
+=== What sail is not 
+Sail is not an RTL (Register Transfer Language).
+There is no direct support for timing (as in clock
+timing) and there is no support for parallel execution,
+all things that an RTL contains.
+
+=== version management and what to expect
+TBD
+
+[#platform-configuration]
+== Platform Configuration example (Bill)
+
+== FAQs (Frequently Asked Questions)
+
+Following are a set of FAQs that were generated via set of questions to the Sail developers.
+
+include::./RISCV_model_FAQ.adoc[]
+

cookbook/functional_code_examples/br_j_asm/CMakeLists.txt

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# SPDX-FileCopyrightText: Copyright 2019-2021 Siemens. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+cmake_minimum_required(VERSION 3.10 FATAL_ERROR)
+
+find_program(CMAKE_ASM_COMPILER riscv64-unknown-elf-gcc HINTS /opt/riscv/bin)
+set(CMAKE_ASM_LINK_EXECUTABLE "<CMAKE_LINKER> <LINK_FLAGS> <OBJECTS> <LINK_LIBRARIES> -o <TARGET>")
+
+project(br_j_asm ASM)
+
+add_executable(br_j_asm.riscv test.S)
+
+set(CONFIG_BASE 0x20010000)
+set(CMAKE_ASM_FLAGS -DCONFIG_BASE=${CONFIG_BASE})
+# If using cmake > 3.13 you could use
+#add_link_options(-T ${CMAKE_SOURCE_DIR}/riscv_test.ld.spike)
+# instead of setting LINK_FLAGS
+set_property(TARGET br_j_asm.riscv APPEND_STRING PROPERTY LINK_FLAGS " -T ${CMAKE_SOURCE_DIR}/riscv_test.ld.spike")