eive-obsw/README.md

# <a id="top"></a> <a name="linux"></a> EIVE On-Board Software

## General information
* OBC
	* Xiphos Q7S
	* Based on Zynq-7020 SoC (xc7z020clg484-2)
		* Dual-core ARM Cortex-A9 
		* 766 MHz
		* Artix-7 FPGA (85K pogrammable logic cells)
	* Datasheet at https://eive-cloud.irs.uni-stuttgart.de/index.php/apps/files/?dir=/EIVE_IRS/Arbeitsdaten/08_Used%20Components/Q7S&fileid=340648
* Linux OS
	* Build with Yocto 2.5
	* Linux Kernel https://github.com/XiphosSystemsCorp/linux-xlnx.git
	

## Setting up development environment
* Install Vivado 2018.2 and Xilinx SDK from https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools/archive.html
* For supported OS refer to https://www.xilinx.com/support/documentation/sw_manuals/xilinx2018_2/ug973-vivado-release-notes-install-license.pdf
* Add path of linux cross-compiler to environment variables SDK\2018.2\gnu\aarch32\nt\gcc-arm-linux-gnueabi\bin
* Install make (only on windows, SDK on Linux can use the make installed with the SDK)
	1. Install NodeJS LTS
	2. Install xpm
	````
	npm install --global xpm
	````
	3. Install Windows build tools (after installation also linux commands like mkdir can be used from windows) 
	````
	xpm install --global @xpack-dev-tools/windows-build-tools@latest
	````

### Building the software

1. Clone the repository with
```sh
git clone https://egit.irs.uni-stuttgart.de/eive/eive_obsw.git
```

2. Update all the submodules
```sh
git submodule init
git submodule sync
git submodule update
```

4. Open Xilinx SDK 2018.2
5. Import project
	* File &rarr; Import &rarr; C/C++ &rarr; Existing Code as Makefile Project
6. Set build command 
	* When on Linux right click project &rarr; Properties &rarr; C/C++ Build &rarr; Set build command to make -j
		* -j causes the compiler to use all available cores
	* On windows create a make target (Windows &rarr; Show View &rarr; Make Target)
		* Right click eive_obsw &rarr; New &rarr; 
		* Target name: all
		* Uncheck "Same as the target name"
		* Uncheck "Use builder settings"
		* As build command type: <path to make>\make -j all WINDOWS=1
7. Run build command (double click the generated target)

### Debugging the software
1. Assign static IP address to Q7S
	* Open serial console of Q7S (Accessible via the micro-USB of the PIM, see also Q7S user maunal chapter 10.3)
	* Baudrate 115200
	* Login to Q7S:
		* user: root
		* pw: root
	* Set IP address and netmask with
	````
	ifconfig eth0 192.168.133.10
	ifconfig eth0 255.255.255.0
	````
2. Connect Q7S to workstation via ethernet
3. Make sure the netmask of the ehternet interface of the workstation matches the netmask of the Q7S
	* When IP address is set to 192.168.133.10 and the netmask is 255.255.255.0, an example IP address for the workstation
	  is 192.168.133.2
4. Run tcf-agent on Q7S
	* Tcf-agent is not yet integrated in the rootfs of the Q7S. Therefore build tcf-agent manually
	````
	git clone git://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git
	cd org.eclipse.tcf.agent/agent
	make CC=arm-linux-gnueabihf-gcc LD=arm-linux-gnueabihf-ld MACHINE=arm NO_SSL=1 NO_UUID=1
	````
	* Transfer executable agent from org.eclipse.tcf.agent/agent/obj/GNU/Linux/arm/Debug to /tmp of Q7S
	````
	cd obj/GNU/Linux/arm/Debug
	scp agent root@192.168.133.10:/tmp
	````
	* On Q7S 
	````
	cd /tmp
	chmod +x agent
	````
	* Run agent
	````
	./agent
	````
5. In Xilinx SDK 2018.2 right click on project &rarr; Debug As &rarr; Debug Configurations
6. Right click Xilinx C/C++ applicaton (System Debugger) &rarr; New &rarr; 
7. Set Debug Type to Linux Application Debug and Connectin to Linux Agent
8. Click New
9. Give connection a name
10. Set Host to static IP address of Q7S. e.g. 192.168.133.10
11. Test connection (This ensures the TCF Agent is running on the Q7S)
12. Select Application tab
	* Project Name: eive_obsw
	* Local File Path: Path to eiveobsw-linux.elf (in _bin\linux\devel)
	* Remote File Path: /tmp/eive_obsw.elf

### Setting up UNIX environment for real-time functionalities
Please note that on most UNIX environments (e.g. Ubuntu), the real time functionalities 
used by the UNIX pthread module are restricted, which will lead to permission errors when creating these tasks
and configuring real-time properites like scheduling priorities.

To solve this issues, try following steps:

1. Edit the /etc/security/limits.conf 
file and add following lines at the end:
```sh
<username>   hard   rtprio  99
<username>   soft   rtprio  99
```
The soft limit can also be set in the console with `ulimit -Sr` if the hard
limit has been increased, but it is recommended to add it to the file as well for convenience.
If adding the second line is not desired for security reasons,
the soft limit needs to be set for each session. If using an IDE like eclipse 
in that case, the IDE needs to be started from the console after setting
the soft limit higher there. After adding the two lines to the file,
the computer needs to be restarted.

It is also recommended to perform the following change so that the unlockRealtime
script does not need to be run anymore each time. The following steps
raise the maximum allowed message queue length to a higher number permanently, which is 
required for some framework components. The recommended values for the new message
length is 130.

2. Edit the /etc/sysctl.conf file
```sh
sudo nano /etc/sysctl.conf
```
Append at end: 
```sh
fs/mqueue/msg_max = <newMsgMaxLen>
```
Apply changes with: 
```sh
sudo sysctl -p
```

A possible solution which only persists for the current session is
```sh
echo <newMsgMax> | sudo tee /proc/sys/fs/mqueue/msg_max
```
or running the `unlockRealtime` script.

3. Run the shell script inside the linux folder
```sh
./unlockRealtime
```
This script executes the `sudo setcap 'cap_sys_nice=eip' \<application\>`
command on the binaries, increases the soft real time limit of the current
session and increases the maximum number of message queues by setting
`/proc/sys/fs/mqueue/msg_max`.
All changes are only applied for the current session (read 2. and 3. for 
a permanent solution). If running the script before executing the binary does
not help or an warning is issue that the soft real time value is invalid, 
the hard real-time limit of the system might not be high enough (see step 1).

### Flight Software Framework (FSFW)

An EIVE fork of the FSFW is submodules into this repository.
To add the master upstream branch and merge changes and updates from it 
into the fork, run the following command in the fsfw folder first:

```sh
git remote add upstream https://egit.irs.uni-stuttgart.de/fsfw/fsfw.git
git remote update --prune
```

After that, an update can be merged by running

```sh 
git merge upstream/master
```

Alternatively, changes from other upstreams (forks) and branches can be merged like that in
the same way.