clean repo

Signed-off-by: Frosty <[email protected]>

.gitignore

@@ -0,0 +1,2 @@
+/.non_public
+/.idea

Code/Docs/client_protocol/Introduction.md

@@ -0,0 +1,50 @@
+猎鹿人餐馆已经准备了一个 Unity客户端（以下简称 客户端），需要你使用 Uart 与客户端进行通信，并将你在开发板上的操作反映到客户端里。好消息是，一个现成的 Uart 模块已经在框架中为你准备好。你只需要以此为基础，在你的开发板上实现一套与客户端对应的应用层协议。
+
+The GenshinHunter Restaurant has prepared a Unity software named GenshinKitchen.exe, and it requires you to communicate with the software using UART to reflect your actions on the development board in the software. The good news is that a ready-made UART module has been prepared for you. You only need to build a simple protocol on your development board that corresponds to the kitchen software, based on this module.
+
+## What is UART?
+UART(通用异步收发传输器)是一种通信协议，在本项目中充当了客户端和开发板交互的渠道。
+
+UART(Universal Asynchronous Transceiver Transmitter) is a communication protocol that acts as a channel for interaction between the client and the development board in this project.
+
+![overview](../hdl_framework/overview.png)
+
+在该项目中，你不需要知道UART底层的工作原理是什么，而是为你提供了一个封装好的UART模块，如上图（详细见 *HDL framework -- UART module*）。在图中，**T4和N5管脚的另一端就连接着电脑客户端。**
+
+In this project, you do not need to know how the underlying UART works, but provide you with a encapsulated UART module as shown in the image above (see *HDL framework - UART module*). In the image, **the other end of the T4 and N5 pin is connected to the client.**
+
+总之，你只需要知道：**传入UART模块的内容(io_dataIn)会由客户端响应，而客户端的信号会由UART模块发给开发板(io_dataOut)。而本章节介绍的，是这些信号的规范。**
+
+Above all, all you need to know is that: **The content passed into the UART module (io_dataIn) is responded to by the client, and the client's signal is sent by the UART module to the development board (io_dataOut). This section describes the specification of these signals. **
+
+## Overview
+
+我们会将整个协议分为两部分: 发送端协议(数据从开发板到客户端), 接收端协议(数据从客户端到开发板).
+
+We will divide the whole protocol into two parts: the sender protocol(from board to client) and the receiver protocol(from client to board).
+Among them, the script transfer part of the receiver protocol is already provided in the framework, so students who are not interested can skip it.
+
+UART模块是以Byte(8bit)为单位依次接受/发送数据的.
+在这个简单的应用层协议中,绝大部分情况下最低2bit都被用于区分频道,而高6bit被用于传输具体数据. 
+
+The UART module receives/sends data in bytes (8 bits).
+In this simple application layer protocol, the minimum 2 bits are used to distinguish channels in most cases, and the high 6 bits are used to transmit specific data.
+
+基本频道区分如下,详情请查看该章节剩余的的文档.
+
+Basic channels are divided as follows, see the rest of the documentation in this section for details.
+
+
+|Roles| Channel | Description|
+|--------|--------|--------------|
+|Sender| XXXXXX00 | Ignored by Client.|
+|Sender| XXXXXX01 | Change the game state.|
+|Sender| XXXXXX10 | Let traveler perform specific operations. |
+|Sender| XXXXXX11 | Let traveler change the target machine. |
+|Receiver| XXXXXX00 | Should be ignored by Board. |
+|Receiver| XXXXXX01 | Feedback signal from Client to Board. |
+|Receiver| XXXXXX10 | Change into Script loading mode.|
+|Receiver| XXXXXX11 | Unused. Should be ignored by Board.| 
+
+
+

Code/Docs/client_protocol/receive_feedback.md

@@ -0,0 +1,17 @@
+## Feedback Signal
+|data[7:6]|data[5:2]|data[1:0]|Description|
+|------|---------|--------|----------|
+|00|xxxx|01|Traveler targeting on specific machine with ID xxxxxx.|
+
+此类指令处于频道0b01,在接收到该条信息时,你可以解析2~5bit来了解厨房的状态.
+每一bit的具体信息如下表.
+
+This type of instruction is on channel 0b01, and when you receive this message, you can parse 2 to 5 bits to understand the state of the kitchen.
+The details of each bit are as follows.
+
+|Signal|Description|
+|------|---------|
+|data[2]|Set(1) when traveler is in front of target machine, otherwise Reset(0).|
+|data[3]|Set(1) when traveler has item in hand, otherwise Reset(0).|
+|data[4]|Set(1) when target machine is processing, otherwise Reset(0).|
+|data[5]|Set(1) when target machine has item, otherwise Reset(0).|

Code/Docs/client_protocol/receive_script.md

@@ -0,0 +1,18 @@
+## Feedback Signal
+|data[7:2]|data[1:0]|Description|
+|------|---------|--------|
+|xxxxxx|10|Switch to **script loading mode** with script size xxxxxx10 bits.|
+
+此类指令处于频道0b10,在接收到该条信息时,你将会切换到脚本加载模式,且脚本大小恰好为xxxxxx10 byte(由client保证).
+
+This type of instruction is on channel 0b10, and upon receiving this message, you will be switched to script load mode and the script size is exactly xxxxxx10 byte(guaranteed by client).
+
+进入脚本加载模式后,接下来接收端收到的xxxxxx10 byte数据都是脚本,他们不应该再被接收端正常解析,  而是应该被存入脚本内存中.
+
+After entering the script loading mode, the following xxxxxx10 bytes of data received by the receiver are scripts, and they should not be parsed by the receiver normally, but should be stored in the script memory.
+
+幸运的是, **我们在框架中为你处理好了脚本协议.** 
+如果你对此不感兴趣的话, 这部分你可以完全不考虑~
+
+Fortunately, **we have taken care of the scripting protocol for you in the framework.** 
+If that doesn't interest you, you can skip that part altogether!

Code/Docs/client_protocol/transmit_oper.md

@@ -0,0 +1,19 @@
+## Traveler Operating Machine
+|data[7] |data[6:2]|data[1:0]|Description|
+|------|--------|--------|----------|
+|x|00001|10|Traveler perform **Get** operation to target Machine.|
+|x|00010|10|Traveler perform **Put** operation to target Machine.|
+|x|00100|10|Traveler perform **Interact** operation to target Machine.|
+|x|01000|10|Traveler perform **Move** operation to target Machine.|
+|x|10000|10|Traveler perform **Throw** operation to target Machine.|
+|x|00000|10|Ignored by Client.|
+|x|other|10|**Illegal Case! Avoid it please!** |
+
+此类指令处于频道0b10,并用5bit的One-hot编码控制厨师执行对应的操作.
+
+Such instructions are on channel 0b10 and use a 5-bit One-hot code to control the chef to perform the corresponding operation.
+
+
+**注意非法情况. 一旦非法情况出现, 我们将会扣分.**
+
+**Be aware of illegal cases. We will deduct your points when they arise.**

Code/Docs/client_protocol/transmit_state.md

@@ -0,0 +1,22 @@
+## Game State Control
+|data[7:4] |data[3:2]|data[1:0]|Description|
+|------|--------|--------|----------|
+|xxxx|01|01|Client would start the game.|
+|xxxx|10|01|Client would stop the game.|
+|xxxx|xx|01|Ignored.|
+
+此类指令处于频道0b01,并用2bit控制游戏开始与结束.
+
+This command is on channel 0b01 and uses 2 bits to control the start and end of the game.
+
+**游戏开始时**,计时器开始计时,机器开始工作,玩家可以通过开发板控制旅行者.
+**游戏结束时**,计时器停止计时,机器停止工作,玩家无法再通过开发板控制旅行者.
+
+** When the game starts **, the timer starts, the machine starts working, and the player can control the traveler through the development board.
+** At the end of the game **, the timer stops, the machine stops working, and the player can no longer control the Traveler through the development board.
+
+多次重复的游戏开始/结束信号会被客户端自行忽略.
+此外,当顾客收到三份菜肴时,游戏会自动结束.
+
+Repeated start/end signals are ignored by the client itself.
+In addition, the game will automatically end when the customer receives three dishes.

Code/Docs/client_protocol/transmit_target.md

@@ -0,0 +1,17 @@
+## Traveler Targeting Machine
+|data[7:2]|data[1:0]|Description|
+|------|--------|----------|
+|xxxxxx|10|Traveler targeting on specific machine with ID xxxxxx.|
+
+此类指令处于频道0b11并传入一个6bit操作数,厨师会将自己的目标机器设为该操作数.
+
+This type of instruction is on channel 0b11 and passes in a 6bit operand, which the chef sets to his target machine.
+
+操作数为0会被客户端忽略, 但操作数大于20会被视为非法情况.
+
+An operand of 0 is ignored by the client. An operand greater than 20 is an illegal case.
+
+
+**注意非法情况. 一旦非法情况出现, 我们将会扣分.**
+
+**Be aware of illegal cases. We will deduct your points when they arise.**

Code/Docs/hdl_framework/Introduction.md

@@ -0,0 +1,14 @@
+我们在框架中提供了UART module和Script Memory两大模块.
+
+We provide two modules in the framework, UART module and Script Memory.
+
+![overview](./overview.png)
+
+
+**UART module**负责建立与客户端的连接,与客户端进行交互(可以看到图中N5和T4就是UART通道).
+
+**UART module** is responsible for establishing connections with and interacting with clients (N5 and T4 in the figure are UART channels).
+
+**Script Memory**负责接收与存储来自客户端的脚本, 然后你就可以从中读取与解析脚本,并执行动作.
+
+**Script Memory** is responsible for receiving and storing scripts from the client, and then you can read and parse the script from it, and perform actions.

Code/Docs/hdl_framework/MEM_module.md

@@ -0,0 +1,31 @@
+# Script Memory Module
+
+我们准备好了一个用于存放脚本的RAM,并处理好了脚本加载部分.
+
+```
+module ScriptMem(
+  input        clock,             // connect to the same wire of UART module
+               reset,             // connect to the same wire of UART module
+  input  [7:0] dataOut_bits,      // connect to the same wire of UART module
+  input        dataOut_valid,     // connect to the same wire of UART module
+  
+  output       script_mode,  // If script_mode is 1, you should ignore the dataOut_bits from UART module
+  input [7:0] pc,      //program counter.
+  output [15:0] script //instructions from pc.
+);
+```
+
+前四个接口直接和UART module的对应接口连接,ScriptMem将会通过这些接口加载脚本. 
+
+The first four interfaces connect directly to the corresponding interfaces on the UART module, and ScriptMem will load scripts through these interfaces.
+
+script_mode信号为1时,代表正在加载脚本状态,此时你不应该尝试处理dataOut_bits的内容,更不应该读取该模块的script信号.
+script_mode信号为0时,你可以提供pc信号(作为地址), 并从script中获得该地址对应的指令.
+
+When the script_mode signal is 1, it means that the script state is being loaded, and you should not attempt to process the contents of the dataOut_bits, much less read the script signal of the module.
+When the script_mode signal is 0, you can provide the pc signal (as the address) and get the corresponding instruction from the script.
+
+注意: pc的地址是以byte(8bit)为单位的. 由于一个指令占2byte(16bit), 你应该时刻保持pc的值为2的倍数. **在顺序执行指令时, 请执行 $pc <= pc + 2$ !**
+
+Note: pc addresses are in bytes (8bit). Since an instruction takes up 2byte(16bit), you should always keep the value of the pc as a multiple of 2. **When executing instructions sequentially, execute $pc <= pc + 2$!**
+

Code/Docs/hdl_framework/UART_module.md

@@ -0,0 +1,27 @@
+# UART module
+
+一个封装好的Uart模块已经提供。你无法直接将开发板的操作映射到软件中，所以你需要这样的Uart模块，将开发板的操作传递给软件，再把软件的反馈信号传回开发板。
+
+Here is a provided Uart module. It’s impossible to map your operations on the EGO1 board to the software, hence you need a UART module like this to transmit the operations from the EGO1 board to the software and then relay the software's feedback signals back to the EGO1 board. 
+
+```
+module UART(
+  input        clock,             // uart clock. Please use 16 x BaudRate. (such as: 9600 * 16 = 153600Hz)
+               reset,             // reset on high.
+               io_pair_rx,        // rx, connect to R5 pin please
+  input  [7:0] io_dataIn_bits,    // (a) byte from DevelopmentBoard => GenshinKitchen
+  output       io_pair_tx,        // tx, connect to T4 pin please
+               io_dataIn_ready,   // referring (a) £»pulse 1 after a byte tramsmit success.
+           reg io_dataOut_valid,  // referring (b)
+  output reg [7:0] io_dataOut_bits    // (b) byte from GenshinKitchen => DevelopmentBoard, only available if io_dataOut_valid=1
+);
+
+```
+
+在你设计的模块中，你需要控制i_data_bit，这是Uart向软件发送的8个比特数据。而软件返回给Uart的8个比特数据存放在o_data_bit中（output_valid=1时有效），你需要接收该数据并使用该数据控制你程序的行为。
+
+In this module, you should modify i_data_bit which is the 8-bits-data send to software by Uart. The 8-bits-data returned to Uart by software is in o_data_bit (only available when output_valid=1), which should be received to control your code.
+
+你可能会需要用到时钟分频，为你的Uart模块提供合适的时间信号，即clock信号。这个时钟的频率大致为Uart比特率的16倍，且误差小于1%。例如软件中默认比特率为9600，那么Uart模块的时钟频率应当为153600Hz。
+
+You may need a new clock with a divided frequency, which can provide a correct time signal to Uart. The clock frequency for this UART module should be approximately 16 times the UART bit rate, with an error of less than 1%. For example, the default bit rate in the software is 9600, then the UART module's clock frequency should be 153600 Hz.

Code/Docs/index.md

@@ -0,0 +1,96 @@
+# Welcome to GenshinKitchen
+
+![sample](./Sample.gif)
+
+**旅行者正在猎鹿人餐馆进行实习，需要你的帮助！**
+
+**The traveler is undergoing an internship at the Huntsman's Restaurant and seeks your assistance!**
+
+
+餐馆里有各种食材，你的任务是使用这些食材，按照给定的配方，操作餐馆的各种设
+施，制作出成品菜肴。
+
+The restaurant is equipped with a variety of ingredients, and your task is to
+utilize these ingredients, operate various facilities within the restaurant, and
+produce finished dishes according to the provided recipes.
+
+**Git repository:** https://github.com/Yan-ice/GenshinKitchen_2023F
+
+*Author: J.Q. Yan, R.X. Jiang, W.Q. Yan*
+
+## Goals
+
+在这个厨房客户端中,操作大厨旅行者的并不是鼠标键盘,也不是手柄,而是你的FPGA开发板. 
+因此,你需要基于我们提供的框架设计一套合适的硬件逻辑来控制旅行者制作菜肴.
+
+In this kitchen client, Chef Traveler is operated not by the mouse and keyboard, nor by the controller, but by your FPGA development board.
+Therefore, you need to design a suitable set of hardware logic based on the framework we provide to control the traveler to make dishes.
+
+## Documentation
+
+除去QuickStart, 整个wiki文档分为4大部分.
+
+1. 在**COOKER HANDBOOK**章节中,我们会介绍客户端中的内容, 包括厨房布局,厨房里的物品,机器等.
+
+2. 在**HDL FRAMEWORK(DEMO)**章节中,我们会介绍为大家提供的HDL框架,帮助大家理解并使用这个框架.
+
+3. 在**CLIENT PROTOCOL**章节中,我们会介绍客户端和开发板之间基于UART的通信协议,让大家更好地完成二者之间的交互.
+
+4. 在**SCRIPT SPECIFICATION**章节中,我们会介绍脚本规范,尽可能清晰明确地阐述脚本的撰写格式与执行要求.
+
+Apart from QuickStart, the entire wiki documentation is divided into four parts.
+
+1. In the chapter of the **COOKER HANDBOOK**, we will introduce the contents of the client, including the kitchen layout, the items in the kitchen, the machines, and so on.
+
+2. In the chapter **HDL FRAMEWORK(DEMO)**, we will introduce the HDL framework for you to help you understand and use this framework.
+
+3. In the chapter **CLIENT PROTOCOL**, we will introduce the UARt-based communication protocol between the client and the development board, so that everyone can better complete the interaction between the two.
+
+4. In the chapter **SCRIPT SPECIFICATION**, we will introduce the script specification, and explain the script writing format and execution requirements as clearly and explicitly as possible.
+
+## QuickStart
+
+建议大家先尝试QuickStart内容,帮助大家快速上手.
+
+It is recommended that you try the QuickStart content first to help you get started quickly.
+
+## Repository
+项目仓库结构如下:
+```
+GenshinKitchen/
+	Doc/
+		index.md
+		...
+	GenshinKitchen_Client/
+		GenshinKitchen_Windows/
+		GenshinKitchen_Linux/
+	HDL_Framework/
+		GenshinKitchen.srcs/
+		GenshinKitchen.xpr
+	QuickStart/
+		ScriptDemo.bit
+		ManualDemo.bit
+		Script_MakeManjuu.txt
+	README.md
+	icon.png
+	
+```
+
+**Doc** 包含此文档的本地版本（但可能不是最新的）。
+
+**GenshinKitchen_Client** 包含Unity制作的多平台软件客户端.
+
+**QuickStart** 包含帮助你快速上手的内容.
+
+**HDL_Framework** 包含我们提供的HDL框架.
+
+
+**Doc** Contains a local version of this document (but it may not be up to date).
+
+**GenshinKitchen_Client** includes multi-platform software client produced by Unity Free Edition.
+
+**QuickStart** contains content to help you get started quickly.
+
+**HDL_Framework** contains the basic HDL framework we provide.
+
+

Code/Docs/machine_and_item/Introduction.md

@@ -0,0 +1,42 @@
+在厨房中, 若干种食材经过一定的合成配方可以变成美味的菜肴.
+在这一章节中,我们会依次介绍配方类型,食材和加工用的机器.
+
+In the kitchen, several ingredients can be transformed into delicious dishes via certain recipes.
+In this section, we will look at the types of recipes, the ingredients and the machines used for processing.
+
+可能出现的物品一共有大约20种,其中6种是可以直接获取的基本食材, 除此之外的其他食材都有自己的特定合成配方.
+
+There are a total of about 20 possible items, six of which are basic ingredients that can be obtained directly, and the rest have their own specific recipes.
+
+在合成配方中，有三种针对食物的处理操作，分别是加工、组合、烹饪。厨房里有对应的机器能够对食材执行这些操作。
+
+There are three possible operations for food, namely Processing, Combining, Cooking. There are machines that can perform these operations on the ingredients.
+
+
+餐厅中一共有 20 个机器，依次具有编号 1~20, 如下表。他们各自具有自己的功能, 有的能产出食物,有的能存放食物,有的能加工食物.
+
+There are a total of 20 machines in the restaurant with serial numbers 1 to 20, as shown in the following table. They each have their own function, some can produce food, some can store food, and some can process food.
+
+|Machine ID|	Machine Type|
+|------|------|
+|1	|Storage crate with sweet flowers|
+|2	|Storage crate with wheat|
+|3	|Storage crate with raw meat|
+|4	|Storage crate with salt|
+|5	|Storage crate with berries|
+|6	|Storage crate with Jueyun Chili|
+|7	|Stone mill|
+|8	|Cutting machine|
+|9	|Table|
+|10	|Stove|
+|11	|Table|
+|12	|Oven|
+|13	|Oven|
+|14	|Table|
+|15	|Workbench|
+|16	|Mixer|
+|17	|Table|
+|18	|Customer|
+|19	|Table|
+|20	|Trash bin|
+