Merge branch 'update_docs' into 'devel'

Update docs

See merge request YARR/YARR!105

CONTRIBUTING.md

+# General Guidelines
+
+## Branch setup
+- ``master`` : Release branch, only stable code from the ``devel`` branch to merged into here.
+- ``devel`` : Development staging branch, all feature branches are to be merged in here for testing before getting merged into ``master``.
+
+Developers shall commit their code to a new branch, which is feature-oriented i.e. that different features should be developed in seperate branches. Every branch should have an open Issue or Merge Request once it's pushed to the main repository.
+
+## Single or Occasional Commits
+If you expect to only commit code occasionaly or a single time the best way to contribute is to fork the repository and submit a merge request from your personal repository to the ``devel`` branch of the YARR repository.
+
+## Full Developer or Frequent Commits
+If you would like to become a full developer or expect to perform more frequent commits please subscribe to the [yarr-devel](https://e-groups.cern.ch/e-groups/EgroupsSubscription.do?egroupName=yarr-devel) mailing list. Once approved you can push your development branch to the YARR repository and once ready create a merge request into the ``devel`` branch.
+
+# Coding Style
+
+No specific style is enforced, that being said if you edit existing code adhere to existing coding style.
+
+Soon enough we will add a style checker.

README.md

@@ -8,46 +8,48 @@ Documentation covering installation and usage can be found here http://yarr.rtfd
 
 ## Mailing list
 
-Subscribe to the CERN mailing list: [yarr-user](https://e-groups.cern.ch/e-groups/EgroupsSubscription.do?egroupName=yarr-users)
+Users should subscribe to the CERN mailing list to receive announcements for important updates: [yarr-user](https://e-groups.cern.ch/e-groups/EgroupsSubscription.do?egroupName=yarr-users)
 
-## Supported Hardware:
-The YARR SW supports multiple hardware platforms which have been integrated:
+Developers and potential developers please refer to [Contribution](CONTRIBUTING.md) guide.
 
-- YARR PCIe cards (SPEC and XpressK7): link
-- IBL BOC: link
-- Wup KU40: link
-- RCE HSIO2: link
+## Quick Install Guide
 
-## Requirements
-Hardware:
+### Hardware:
 
-- Update me
+- Please refer to the [documentation](http://readthedocs.org/projects/yarr/badge/?version=latest) for details
 
-Software:
+### Software:
 
-- SLC6 (Scientific Linux CERN 6) or CC7 (CERN CentOs 7)
+Requirements:
+
+- CC7 (CERN CentOs 7) 
 - GCC version 7.0 or higher
-    - for example from devtoolset-7, instruction can be found here https://www.softwarecollections.org/en/scls/rhscl/devtoolset-4
+    - for example from devtoolset-7, instruction can be found [here](https://yarr.readthedocs.io/en/latest/install/#hardware-setup-and-software-installation)
+
+Quick Default Install Guide:
 
-Quick Install Guide:
 - Using make:
-    - cd YARR/src
-    - make
+    - ``cd YARR/src``
+    - ``make``
 - Using cmake:
-    - cmake version 2.8 or higher
-        - for MacOS consider installing cmake from homebrew: http://brew.sh
-    - Atlas RCE SDK for cross compilation and running on RCEs (HSIO2 or COB)
-    - to install in /opt/AtlasRceSDK
-        - sudo mkdir -p /opt/AtlasRceSDK
-        - cd /opt/AtkasRceSDK/ ; curl -s  http://rceprojectportal.web.cern.ch/RceProjectPortal/software/SDK/V0.11.1.tar.gz | sudo tar xvfz - 
-    - using CMake:
-        - source /opt/AtkasRceSDK/V0.11.0/setup.sh # for RCEs
-        - cd YARR/src
-        - mkdir <builddir>
-        - cd <buildir>
-        - select one of the supported toolchains
-            - make ..  -DCMAKE_TOOLCHAIN_FILE=../cmake/linux-clang # requires clang installed on Linux
-            - make ..  -DCMAKE_TOOLCHAIN_FILE=../cmake/linux-gcc # gcc 4.8 or higher
-            - make ..  -DCMAKE_TOOLCHAIN_FILE=../cmake/rce-gcc # ARM/Archlinux on RCE
-            - make ..  -DCMAKE_TOOLCHAIN_FILE=../cmake/macos-clang # MacOS build
-        - make
+    - ``cd YARR``
+    - ``mkdir build``
+    - ``cd build``
+    - or select one of the supported toolchains
+        - make ..  -DCMAKE_TOOLCHAIN_FILE=../cmake/linux-clang # requires clang installed on Linux
+        - make ..  -DCMAKE_TOOLCHAIN_FILE=../cmake/linux-gcc # gcc 4.8 or higher
+        - make ..  -DCMAKE_TOOLCHAIN_FILE=../cmake/rce-gcc # ARM/Archlinux on RCE
+        - make ..  -DCMAKE_TOOLCHAIN_FILE=../cmake/macos-clang # MacOS build
+    - ``make``
+
+
+Quick RCE Install Guide:
+
+- source /opt/AtkasRceSDK/V0.11.0/setup.sh # for RCEs
+- Atlas RCE SDK for cross compilation and running on RCEs (HSIO2 or COB)
+- to install in /opt/AtlasRceSDK
+    - sudo mkdir -p /opt/AtlasRceSDK
+    - cd /opt/AtkasRceSDK/ ; curl -s  http://rceprojectportal.web.cern.ch/RceProjectPortal/software/SDK/V0.11.1.tar.gz | sudo tar xvfz - 
+        
+
+Quick NetIO Install Guide:

docs/index.md

@@ -27,6 +27,7 @@ Support for YARR can be found in the [YARR Matter Most channel.](https://matterm
 * PCIe Installation
     * [PCIe Kernel Driver Installation](kernel_driver.md)
     * [PCIe Firmware Setup](pcie.md)
+    * [External PCIe](pcie_ext.md)
 * [ScanConsole](scanconsole.md)
     * [FE-I4](fei4.md)
     * [FE65-P2](fe65p2.md)

docs/pcie_ext.md

+# External PCIe Setup
+
+![External PCIe Setup](images/ext_pcie_setup.jpg)
+
+It is possible to run YARR without a dedicated computer through a PCIe to Thunderbolt 3 adapter. You need:
+
+ * a computer with Thunderbolt 3 port (e.g. Thinkpad X1 Carbon or Dell Latitude E5591, both successfully tested);
+ * a PCIe to Thunderbolt 3 adapter (successfully tested [this one](https://www.startech.com/CH/en/Cards-Adapters/Slot-Extension/thunderbolt-3-pcie-expansion-chassis~TB31PCIEX16) which can be bought e.g. from [Amazon.com](https://www.amazon.com/StarTech-com-Thunderbolt-PCIe-Expansion-Chassis/dp/B075RJHLB4/ref=sr_1_3) or [microspot](https://www.microspot.ch/de/computer-gaming/pc-komponenten/geh%C3%A4use--c586000/startech-com-pcie-erweiterungsgeh%C3%A4use--p0001424460) in Switzerland;
+ * a TB3 to TB3 cable, whereas good USB-C to USB-C should also work and is cheaper.
+
+## Important Information
+ * All Thunderbolt 3 support settings in BIOS should be enabled as described [here](https://it.nmu.edu/docs/thinkpad-thunderbolt-3-dock-set).
+ * You might have to switch on the direct access and authorise the Thunderbolt 3 device as shown below.
+ * The case only powers up if connected to the computer. Otherwise it is in a low-power mode and the connected chip loses its configuration.
+ * Currently, the ```specNum``` registered by the computer increases by one on each reconnection of the external PCIe card.
+     * The number has either to be changed in the ```specCfg.json``` accordingly (up to maximum 9), or
+     * the kernel driver has to be reloaded ```sudo modprobe -r specDriver && sudo modprobe -v specDriver```
+![Bios setting for Thunderbolt 3](images/biosTB3.png)
+![Thunderbolt 3 device authorisation](images/tb3cc7.png)

docs/rd53a.md

@@ -178,6 +178,8 @@ Once the full tuning routine (as outlined in the beginning of this page) has bee
 
 ## Cross-talk
 
+For more information please have a look at [this presentation](https://cernbox.cern.ch/index.php/s/DubCyTMyoWfZ52g).
+
 The cross-talk is evaluated injecting in the neighboring pixels and checking the occupancy in the central pixel. 
 
 To check if there is cross-talk for your chip+sensor, use the following command:
@@ -208,6 +210,90 @@ Example of the s-curve, threshold distribution, threshold map and noise distribu
 ![S-curve threshold scan](images/JohnDoe_crosstalkscan_sCurve.png)
 ![Threshold distribution](images/JohnDoe_crosstalkscan_ThrehsoldDist.png)
 
+## Cross-talk - check bump bonding scheme
+
+To run do
+```bash
+bin/scanConsole -r configs/controller/specCfg.json -c configs/connectivity/example_rd53a_setup.json -s configs/scans/rd53a/std_crosstalk_scan_checkBumpBonding.json  -p
+```
+There are 2 ways to bump bond $25 \times 100 \mu m^2$ sensor pixels onto the $50 \times 50 \mu m^2$ chip pixels. This scan shows crosstalk for sensor type 1 and no crosstalk for sensor type 0 ($50 \times 50 \mu m^2$) or 2 ($25 \times 100 \mu m^2$ but different bump bonding scheme than type 1) as can be distinguished below:
+
+![Check Bump Bonding Scheme type 1](images/0x0A59_ThresholdMap-0_STACK_BumpBond.png)
+![Check Bump Bonding Scheme type 0](images/0x0A57_ThresholdMap-0_STACK_BumpBond.png)
+
+
+## Disconnected Bump Scan
+
+Uses crosstalk scan to identify pixels without any crosstalk - which are likely be due to disconnected bumps. Based on analog scan with crosstalk mask. This scan uses the same config parameters as the crosstalk scan.
+Run the following command:
+```bash
+bin/scanConsole -r configs/controller/specCfg.json -c configs/connectivity/example_rd53a_setup.json -s configs/scans/rd53a/std_discbumpscan.json  -p
+```
+
+![disconnected bumps scan](images/JohnDoe_OccupancyMap_DiscBump.png)
+
+## Source Scan
+
+There are 3 different possibilities for a source scan:
+ 1. noise scan (random trigger)
+ 2. external trigger scan with Hit-Or ("self-trigger")
+ 3. external trigger scan with a real trigger, e.g. scintilltor (external trigger)
+ 
+### Random Trigger
+
+Run `std_digitalscan`, `std_analogscan` and at least 3 `std_noisescan` (with the default duration of 5 minutes) before a source scan with random trigger to mask digital/analog bad pixels and noisy pixels.
+Modify in `std_noisescan.json`: ```"createMask": false``` and to prevent changing the enable mask and ```"time": 300``` in seconds to set the scan duration.
+
+#### Known Problem (to be verified)
+The trigger loop in this scan does not sent an ECR signal during the scan. The sync FE does not delete 0-ToT hits in the buffer and/or the EOC logic gets stuck (with too many hits?) if no ECR is sent. Therefore a stripy pattern can occur in the sync FE.
+
+![stripy pattern source scan](images/0x0967_Occupancy_NoiseScanSource.png)
+
+### Hit-Or ("self-trigger")
+
+For the "self-triggering" source scan using Hit-Or as a trigger, a second DP-miniDP cable is needed to connect to the second DP port in the SCC and port B on the Ohio card. The multi-chip firmware cannot be used.
+Instead of the `specCfg.json` `specCfgExtTrigger.json` is to be used. The Hit-Or lines have to be enabled in the chip config:
+```
+"HitOr0MaskDiff0": 65536,
+"HitOr0MaskDiff1": 1,
+"HitOr0MaskLin0": 65536,
+"HitOr0MaskLin1": 1,
+"HitOr0MaskSync": 65536,
+"HitOr1MaskDiff0": 65536,
+"HitOr1MaskDiff1": 1,
+"HitOr1MaskLin0": 65536,
+"HitOr1MaskLin1": 1,
+"HitOr1MaskSync": 65536,
+"HitOr2MaskDiff0": 65536,
+"HitOr2MaskDiff1": 1,
+"HitOr2MaskLin0": 65536,
+"HitOr2MaskLin1": 1,
+"HitOr2MaskSync": 65536,
+"HitOr3MaskDiff0": 65536,
+"HitOr3MaskDiff1": 1,
+"HitOr3MaskLin0": 65536,
+"HitOr3MaskLin1": 1,
+"HitOr3MaskSync": 65536,
+```
+
+### External trigger
+
+One easy way to use the external trigger scan is to connect a scintillator to a TLU and use the DUT interface with the RD45 outputs through a RJ45-DP adapter.
+
+#### Hardware
+ * a scintillator with a PMT
+ * a TLU
+ * a RJ45 cable
+ * a RJ45-DP converter
+ * a second DP-miniDP cable
+ 
+#### Installation
+
+For running the TLU in standalone mode you need to install ```libusb``` and ```libusb-devel``` version 0.1 (!) on your (CentOS) computer.
+Get eudaq from [here](https://github.com/eudaq/eudaq/tree/master/user/tlu) and compile it with ```USER_TLU_BUILD=ON``` option.
+The TLU only produces trigger when the software is running with e.g. ```./EudetTluControl -a 1 -hm 0 -d 1 -i RJ45 -q```. Please refer to the TLU manual for the options.
+The second DP-miniDP cable connects the RJ45-DP connector to port D which should accept TLU input with the non-multichip FW on the FPGA.
+
 
 # Loop Actions
 
@@ -245,6 +331,8 @@ unsigned serial = (core_row*64)+((col+(core_row%8))%8)*8+row%8;
 
 The maximum of the loops defines how many pixels should be activated at one time. E.g. if the max is 64 that means every 64th pixel (1 pixel per core) and requires 64 steps to loop over all pixels. A pattern of enabled pixels in each mask step for ```max = 16``` can be found [here](https://docs.google.com/spreadsheets/d/1VXZn-fp16U6Rsu_GvGmq_fWgU0qwa0niilJ82ZQOYY8/edit?usp=sharing)
 
+![Mask Loop Pattern for max = 16](images/maskloop.png)
+
 Config parameters:
 
  - max ``<int>``: number of mask stages