From 55b632d331ff649bbd950ed953b4e3160743bd3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Laurent=20P=C3=A9tr=C3=A9?= <laurent.petre@cern.ch>
Date: Mon, 31 Jan 2022 19:12:25 +0100
Subject: [PATCH] Update SuperSaaS documentation
---
docs/references/electronics-guide.md | 77 +---------------
docs/setups-description.md | 129 +++++----------------------
2 files changed, 22 insertions(+), 184 deletions(-)
diff --git a/docs/references/electronics-guide.md b/docs/references/electronics-guide.md
index dc0b117..3f4290d 100644
--- a/docs/references/electronics-guide.md
+++ b/docs/references/electronics-guide.md
@@ -1,91 +1,16 @@
-# Electronics guide
+# Electronics Guide
## How to Use This Guide
Hello! Congratulations, you're taking one of the first steps to becoming an expert on the GEM DAQ Electronics. For you to get the most out of this guide there's a couple of things that we should discuss first. The first is how this guide should be used. It's broken down into several sections, each section focuses on a specific topic:
- - [Test Stand Ettiquette](#test-stand-ettiquette): how to use our test stands, not collide with other users, and most importantly the electronic logbook;
- [Back-end Electronics](#back-end-electronics): how to use the [CTP7](#ctp7), the [AMC13](#amc13), and maybe one day the GLIB (I'm looking at you Phase II Upgrade Community);
- [Front-end Electronics](#front-end-electronics): how [LV power](#lv-power) works, how to use the [FEASTMP](#feastmp), the [GBTx](#gbtx), the [Slow Control ASIC (SCA)](#slow-control-asic-sca), the OH FPGA, and most importantly the [VFAT3](#vfat3);
- [Building GEM Software Tools](#building-gem-software);
- [Configuring a Detector](#configuring-a-detector); and
- [Taking Calibration Scans](#taking-calibration--commissioning-data);
-## Test Stand Ettiquette
-
-It's important to realize we are all sharing a set of common equipment and are working toward a common goal. Furthermore you and your coworkers are at various skill levels and possess different degrees of familiarity with the hardware and the software. This brings us to the first important point:
-
-- **Leave the test stand how you found it**.
-
-This specifically refers to the:
-
-1. Test stand infrastructure (e.g. fiber patch panels, power supplies, DAQ computer, etc...), and
-2. State of software (e.g. `rpcmodules`) and firmware of backend electronics.
-
-It can be expected that you would need to configure the front-end electronics for whatever test/developpment you are working on. But the back-end electronics should *always* be left in a useable state for the next user (i.e. how *you* found them).
-
-Moreover if you are not on the list of approved individuals who can modify the hardware/stand infrastructure you should not (if you are wondering if you are on this list it means you are *not*).
-
-Failure to follow these rules makes more work for the expert team, sysadmin/test stand responsible. Failure to conform repeatedly will result in loss of access to the test stand.
-
-Once you realize this you should:
-
-1. [Determing the right test stand to use](#available-test-stands--their-uses),
-2. [Request time on a test stand](#requesting-time-on-gem-test-stands), and
-3. Use the [appropriate e-log](#electronic-logbook) to log all activities.
-
-### Available Test Stands & Their Uses
-The following 904 test stands exist.
-
-| Stand | Location | Purpose |
-| :---: | :------: | :------ |
-| Coffin | Integration Side of 904 | General purpose debugging station. Supports P5 operation, general software development, firmware testing, and trigger development. Only place combined ME1/1+GE1/1 runs can be taken. |
-| V3 Electronics R&D | GEM 904 Lab | Dedicated to testing sustained operation of GE1/1 detectors. |
-| QC8 | GEM 904 Lab | Production test stand for GE1/1 qualification. |
-
-Unless you are involved in, or performing a test for, the sustained operations group or QC8 for GE1/1 qualification you should default to using the "Coffin" setup.
-
-### Test Stand Infrastructure
-
-Mainframes, fiber patch panels, uTCA crate numbers & names, AMC's, etc...
-
-### Electronic Logbook
-
-For each of the test stands described under the [Available Test Stands & Their Uses](#available-test-stands--their-uses) section a corresponding electronic logbook exists; as shown in the table below:
-
-| Stand | E-Log |
-| :---: | :---: |
-| "Coffin" | [904 Integration](https://cmsonline.cern.ch/webcenter/portal/cmsonline/pages_common/elog?__adfpwp_action_portlet=623564097&__adfpwp_backurl=https%3A%2F%2Fcmsonline.cern.ch%3A443%2Fwebcenter%2Fportal%2Fcmsonline%2Fpages_common%2Felog%3FMedia-Type%3Dscreen%26Media-Feature-Scan%3D0%26Media-Feature-Orientation%3Dlandscape%26Media-Feature-Device-Height%3D1050%26Media-Feature-Height%3D789%26_afrWindowMode%3D0%26Media-Feature-Monochrome%3D0%26Font-Size%3D16%26Media-Feature-Color%3D8%26Media-Featured-Grid%3D0%26_afrLoop%3D12894451140606290%26Media-Feature-Resolution%3D192%26Media-Feature-Width%3D1680%26Media-Feature-Device-Width%3D1680%26Media-Feature-Color-Index%3D0%26Adf-Window-Id%3Dw0%26__adfpwp_mode.623564097%3D1&_piref623564097.strutsAction=%2FviewSubcatMessages.do%3FcatId%3D791%26subId%3D799%26page%3D1) |
-| V3 Electronics R&D | [V3 Electronics Testing](https://cmsonline.cern.ch/webcenter/portal/cmsonline/pages_common/elog?__adfpwp_action_portlet=623564097&__adfpwp_backurl=https://cmsonline.cern.ch:443/webcenter/portal/cmsonline/pages_common/elog?__adfpwp_mode.623564097=1&_piref623564097.strutsAction=//viewSubcatMessages.do?catId=791&subId=1511&page=1&fetch=1&mode=expanded) |
-| QC8 | [Cosmic Stand](https://cmsonline.cern.ch/webcenter/portal/cmsonline/pages_common/elog?__adfpwp_action_portlet=623564097&__adfpwp_backurl=https://cmsonline.cern.ch:443/webcenter/portal/cmsonline/pages_common/elog?_piref623564097.strutsAction=//viewSubcatMessages.do?catId=792&subId=793&page=1&fetch=1&mode=expanded) |
-
-When using a test stand you should:
-
- 1. Open an elog once you start using the stand,
- 2. Show commands executed, and when relevant their outputs,
- 3. Summarize the actions taken and the result(s)/problem(s) encountered, and
- 4. State when you are finished using the stand
-
-### Requesting Time on GEM Test Stands
-
-Each stand has it's own requisition page on SuperSAAS to manage testing and ensure we do not collide with other users. To see the available test stands and to request time on nagivate to:
-
-https://www.supersaas.com/schedule/GEM_904_Infrastructure
-
-If you need time on a particular setup you need to understand what hardware you will be using. Will this be just the front-end(s) on a given link? In this case you'll need time on the AMC in question. Will testing involved the front-end being triggered from a trigger source coming from AMC13? Then you'll need time on the uTCA crate in question.
-
-Before trying to modify the above schedules you'll need to first ask for the GEM 904 Shared User Password on SuperSAAS to use the scheduling tools. To do this ask in the `System Setup` channel of the [GEM DAQ Mattermost Team](https://mattermost.web.cern.ch/signup_user_complete/?id=ax1z1hss5fdm8bpbx4hgpoc3ne). When scheduling you need to provide an:
-
-- Your name
-- Your email
-- Estimated time your test will take (starting & ending time),
-- Phone number you are reachable at while using the test stand, and
-- Description of your test.
-
-Your request will be submitted and then approved. Note you may only use the stand once the request has been *approved*. Once your request has been approved and you start using the stand you still are require to make an elog entry documenting the actiosn you have taken, their outcome, and relevant commands, etc...
-
## Back-end Electronics
---------------------
### AMC13
diff --git a/docs/setups-description.md b/docs/setups-description.md
index cb0b016..85c0ca2 100644
--- a/docs/setups-description.md
+++ b/docs/setups-description.md
@@ -133,127 +133,40 @@ Setup on Windows is an exercise left for the reader.
## Integration setup usage
-It is important to realize we are all sharing a set of common equipment
-and are working towards a common goal. Furthermore you and your
-coworkers may have different skill levels and possess varying degrees of
-familiarity with the hardware and the software. This brings us to the
-first important point:
+It is important to realize we are all sharing a set of common equipment and are working towards a common goal.
+Furthermore you and your coworkers may have different skill levels and possess varying degrees of familiarity with the hardware and the software.
+This brings us to the first important point:
!!! warning
- **Leave the teststand how you found it**.
+ **Leave the setup in a working state**.
- This specifically refers to the:
+ This specifically refers to the setup infrastructure (e.g., fiber patch panels, power supplies, DAQ computer, etc...) and electronics.
- 1. Teststand infrastructure (e.g., fiber patch panels, power supplies,
- DAQ computer, etc\...), and
- 2. State of software (e.g., `rpcmodules`) and firmware of backend
- electronics.
+It can be expected that you would need to configure the back-end and/or front-end electronics for whatever test/development you are working on.
+But the setup should *always* be left in a usable state for the next user.
-It can be expected that you would need to configure the front-end
-electronics for whatever test/development you are working on. But the
-back-end electronics should *always* be left in a usable state for the
-next user (i.e., at worst, exactly how *you* found them).
+Moreover, if you are not on the list of approved individuals who can modify the hardware/stand infrastructure you should not (if you are wondering if you are on this list it probably means you are *not*).
+Failure to follow these rules makes more work for the DAQ expert team, setup responsible/sysadmin.
-Moreover, if you are not on the list of approved individuals who can
-modify the hardware/stand infrastructure you should not (if you are
-wondering if you are on this list it probably means you are *not*).
+### Requesting time on GEM setups
-Failure to follow these rules makes more work for the DAQ expert team,
-sysadmin/teststand responsible. Failure to conform repeatedly may result
-in loss of access to the teststand.
+Each setup has its own requisition page on SuperSaaS to manage testing and ensure we do not collide with other users.
+To see the available setups and to request time on navigate to:
-Once you realize this you should:
+<https://www.supersaas.com/schedule/GEM_Infrastructure>
-1. Determine the right teststand to use
- `gemos-available-teststands`{.interpreted-text role="ref"}
-2. Request time on a teststand
- `gemos-teststand-booking`{.interpreted-text role="ref"}
-3. Use the appropriate e-log `gemos-elogs`{.interpreted-text
- role="ref"} to log all activities
+Before trying to modify the above schedules you'll need to first ask for the GEM Infrastructure shared password on SuperSaaS to use the scheduling tools.
+To do this ask one of the DAQ expert, setup responsible/sysadmin.
-### Available teststands & their uses
-
-The following 904 teststands exist
-
- ------------------------------------------------------------------------
- Stand Location Purpose
- ----------------- ------------------- ----------------------------------
- QC8 GEM 904 lab Production teststand for GE1/1
- qualification
-
- QC7 GEM 904 lab Electronics quality control and
- chamber assembly QC
-
- V3 Electronics GEM 904 lab Testing sustained operations of
- R&D GE1/1 detectors
-
- Coffin 904 integration lab General purpose debugging, support
- P5 operations, software
- development and testing, firmware
- testing, trigger development, CSC
- integration
- ------------------------------------------------------------------------
-
-Unless you are involved in, or performing a test for, the sustained
-operations group or QC8 for GE1/1 qualification you should default to
-using the "Coffin" setup.
-
-### Teststand infrastructure
-
-Mainframes, fiber patch panels, μTCA crate numbers & names, AMC's,
-etc...
-
-### Electronic logbook (e-log)
-
-For each of the teststands described in the section
-`gemos-available-teststands`{.interpreted-text role="ref"}, a
-corresponding electronic logbook exists, as shown in the table below:
-
- Stand E-Log
- -------------------- ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- "Coffin" [904 Integration](https://cmsonline.cern.ch/webcenter/portal/cmsonline/pages_common/elog?__adfpwp_action_portlet=623564097&__adfpwp_backurl=https%3A%2F%2Fcmsonline.cern.ch%3A443%2Fwebcenter%2Fportal%2Fcmsonline%2Fpages_common%2Felog%3FMedia-Type%3Dscreen%26Media-Feature-Scan%3D0%26Media-Feature-Orientation%3Dlandscape%26Media-Feature-Device-Height%3D1050%26Media-Feature-Height%3D789%26_afrWindowMode%3D0%26Media-Feature-Monochrome%3D0%26Font-Size%3D16%26Media-Feature-Color%3D8%26Media-Featured-Grid%3D0%26_afrLoop%3D12894451140606290%26Media-Feature-Resolution%3D192%26Media-Feature-Width%3D1680%26Media-Feature-Device-Width%3D1680%26Media-Feature-Color-Index%3D0%26Adf-Window-Id%3Dw0%26__adfpwp_mode.623564097%3D1&_piref623564097.strutsAction=%2FviewSubcatMessages.do%3FcatId%3D791%26subId%3D799%26page%3D1)
- V3 Electronics R&D [V3 Electronics Testing](https://cmsonline.cern.ch/webcenter/portal/cmsonline/pages_common/elog?__adfpwp_action_portlet=623564097&__adfpwp_backurl=https://cmsonline.cern.ch:443/webcenter/portal/cmsonline/pages_common/elog?__adfpwp_mode.623564097=1&_piref623564097.strutsAction=//viewSubcatMessages.do?catId=791&subId=1511&page=1&fetch=1&mode=expanded)
- QC8 [Cosmic Stand](https://cmsonline.cern.ch/webcenter/portal/cmsonline/pages_common/elog?__adfpwp_action_portlet=623564097&__adfpwp_backurl=https://cmsonline.cern.ch:443/webcenter/portal/cmsonline/pages_common/elog?_piref623564097.strutsAction=//viewSubcatMessages.do?catId=792&subId=793&page=1&fetch=1&mode=expanded)
-
-When using a teststand you should:
-
-1. Open an elog once you start using the stand,
-2. Show commands executed, and when relevant their outputs,
-3. Summarize the actions taken and the result(s)/problem(s)
- encountered, and
-4. State when you are finished using the stand
-
-### Requesting time on GEM teststands
-
-Each stand has its own requisition page on SuperSAAS to manage testing
-and ensure we do not collide with other users. To see the available
-teststands and to request time on navigate to:
-
-<https://www.supersaas.com/schedule/GEM_904_Infrastructure>
-
-If you need time on a particular setup you need to understand what
-hardware you will be using. Will this be just the front-end(s) on a
-given link? In this case you'll need time on the AMC in question. Will
-testing involved the front-end being triggered from a trigger source
-coming from AMC13? Then you'll need time on the μTCA crate in question.
-
-Before trying to modify the above schedules you'll need to first ask
-for the GEM 904 Shared User Password on SuperSAAS to use the scheduling
-tools. To do this ask in the `System Setup` channel of the [GEM DAQ
-Mattermost
-Team](https://mattermost.web.cern.ch/signup_user_complete/?id=ax1z1hss5fdm8bpbx4hgpoc3ne).
When scheduling you need to provide:
-- Your name
-- Your email
-- Estimated time your test will take (starting & ending time)
-- Phone number you are reachable at while using the teststand
-- Description of your test
+- Your name
+- Your email
+- Estimated time your test will take (starting & ending time)
+- Description of your test
Your request will be submitted and then approved.
!!! note
- You should only use the stand once the request has been *approved*. Once
- your request has been approved and you start using the stand you still
- are require to make an elog entry documenting the actions you have
- taken, their outcome, and relevant commands, etc\...
+ Any non-overlaping request is considered as immediately approved and you can start using the stand.
+ In case of long or overlaping requests, please contact the setup responsible.
--
GitLab