update artiq-6 instructions

Signed-off-by: Egor Savkin <es@m-labs.hk>

src/SUMMARY.md

@@ -30,4 +30,5 @@
   - [Moninj](./sw_sup/moninj.md)
   - [Clocking](sw_sup/clocking.md)
   - [device_db.py](sw_sup/device_db.md)
-  - [Setup your PC for building ARTIQ firmware](sw_sup/setup_build_pc.md)
+  - [Setup your PC for building ARTIQ firmware](sw_sup/setup_build_pc.md)
+  - [AFWS client](sw_sup/afws_client.md)

src/build_test_firmware.md

@@ -41,7 +41,7 @@ mkdir <variant>
 cd <variant>/
 nix develop github:m-labs/artiq\?ref=release-8#boards
 # master/standalone only
-artiq_mkfs -s ip 192.168.1.75 kasli.config
+artiq_mkfs -s ip 192.168.1.75/24 kasli.config
 artiq_flash storage -f kasli.config
 artiq_ddb_template -o device_db.py <variant>.json 
 python -m artiq.gateware.targets.kasli <variant>.json 

src/sw_sup/afws_client.md

@@ -0,0 +1,138 @@
+# AFWS client
+
+This article is intended to help with using the `afws_client` command properly.
+
+## Usage
+
+### What is AFWS
+
+AFWS (ARTIQ FirmWare Service) - a service, that allows building customer tailored firmware and gateware (binaries) on M-Labs's servers, 
+and receive these binaries in ready-to-flash format. Subscription to this service also includes helpdesk support,
+and thus is paid on yearly basis (contact sales for prices). It is also typically included when purchasing Carrier (Kasli/Kasli-SoC) for a year, 
+or one-time when purchasing standalone cards for existing crate. Each variant/carrier requires its own subscription.
+
+### What do I need for obtaining binaries
+
+You'll need to have credentials - username and password, which you can obtain from helpdesk, if you haven't yet. 
+Don't forget to specify variant (sticker on top of the crate) that you need to obtain binaries for.
+
+### When do I need to update
+
+In most cases there is no need to update the firmware, unless you encountered a bug and the fix was backported to your version.
+However, if you: changed the layout of the cards - either moved EEM connections, added or deleted cards; 
+changed modes/configurations of the cards (e.g. enable/disable SUServo, synchronization, edge counter, SED lanes etc.).
+In such cases, these changes need to be authorized through helpdesk.
+
+### How to
+
+The base command looks like this:
+```shell
+afws_client <username> build <afws_directory> <variant>
+```
+
+Where (remove `<` and `>`):
+* `<username>` - your username from credentials
+* `<afws_directory>` - the directory/folder, into which you wish to save the binaries
+* `<variant>` - name of the crate/variant. It's optional if you have only one variant in the account
+
+After running this command, it will ask you for the password (the line will remain blank for security reasons).
+If everything matches (username and password are correct, specified variant is in your account and not expired), 
+AFWS will start building the firmware, which takes 10-15 minutes. Sometimes there might be some problems, in which 
+case don't hesitate to contact helpdesk.
+
+After the build done, the AFWS client will automatically download the binaries into `<afws_directory>`, from which 
+you can flash them into your Carrier.
+
+#### View build logs
+
+You may want to view the build logs (for example, in case of problems with configuration). 
+For this, add `--log` option after build:
+
+```shell
+afws_client <username> build --log <afws_directory> <variant>
+```
+
+#### Specify version
+
+By default, AFWS client tries to figure out the installed ARTIQ version. However it works only for Kasli, and not Kasli-SoC.
+It also may fail to determine ARTIQ version if you are using AFWS client without ARTIQ installation.
+Additionally, you may want to specify version regardless of installed version.
+In all these cases, you'll need to specify **both** `--major-ver` and `--rev` arguments, so your command will look like this:
+
+```shell
+afws_client <username> build --major-ver <MAJOR_VER> --rev <REV> <afws_directory> <variant>
+```
+
+Where:
+* `MAJOR_VER` - ARTIQ major version,  either `7` (legacy), `8` (current stable), 
+  `9` (current beta) or `10` (experimental with `nac3` compiler)
+* `REV` - revision from respective branch and repository - i.e. commit hash. You may obtain it either from:
+  * [ARTIQ repository](https://github.com/m-labs/artiq) (for Kasli 2.0 and earlier) by 
+    [selecting branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository)
+    and selecting `XXX commits` above list of files. From here, the list of commits in specified branch will appear 
+    and you will be able to choose the commit and press ["Copy full SHA for YYY"](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits#using-the-file-tree) 
+    button in the right side.
+  * [ARTIQ on Zynq repository](https://git.m-labs.hk/M-Labs/artiq-zynq) (for Kasli-SoC). In similar way to GitHub, 
+    you can choose branch, commit history and copy SHA1 of the commit.
+
+The branches currently map as following:
+* ARTIQ-7 - release-7
+* ARTIQ-8 - release-8
+* ARTIQ-9 - master
+* ARTIQ-10 - nac3
+
+The binaries you receive are "pure" - if the inputs are the same (same version,
+same JSON), the system outputs exactly the same binaries, and if you did it recently, they will be obtained from Nix
+cache (i.e. not rebuilt).
+
+#### Change password
+
+After you received credentials from us, we strongly recommend changing the password as soon as possible via 
+`afws_client <username> passwd` command. This command will ask you for existing password and new desired password.
+
+The passwords are stored in a hashed way (i.e. cannot be decrypted back), however it's your responsibility to choose good passwords.
+Just keep in mind, that password may contain only alpha-numeric symbols and underscore `[a-zA-Z0-9_]`. If it contains other symbols,
+they may be silently ignored and you will not be able to log in.
+If you cannot login, we may reset your password if you email us at helpdesk.
+
+#### Get variants
+
+You may get variants, which are tied to your account by using `get_variants` command:
+```shell
+afws_client <username> get_variants
+```
+
+It will ask for password and output the variants and their respective expiry date:
+
+```text
++-----------+-------------+
+|  Variant  | Expiry date |
++-----------+-------------+
+|   test    |  2028-02-08 |
+|   test3   |  2042-08-08 |
++-----------+-------------+
+```
+
+#### Get JSONs
+
+Sometimes you may want to view the JSON description, from which AFWS is building the variant. With the JSON, you can
+later build the firmware by yourself and/or generate device_db file. The command looks like this (variant 
+needs to be valid, i.e. not expired and authorized in your account):
+
+```shell
+afws_client <username> get_json [-o <OUT>] [-f] <variant>
+```
+
+Specify output file `-o <OUT>`, if you want to save it directly to file `<OUT>`, use `-f` if you want to force 
+overwrite. If you do not specify any of these options, you'll get the JSON description directly in stdin (i.e. in your
+console/terminal).
+
+
+#### Miscellaneous
+
+You may also specify custom AFWS provider with these options (put them before username):
+
+* `--server SERVER` - server to connect to (default: afws.m-labs.hk)
+* `--port PORT` - port to connect to (default: 80)
+* `--cert CERT` - SSL certificate file used to authenticate server (default: use system certificates)
+

src/sw_sup/artiq_legacy.md

@@ -32,6 +32,14 @@ git checkout release-6  # or release-5...
 cd ..
 ```
 
+Keep in mind that ARTIQ-6 scripts have been removed in `nix-scripts`, so you may need to checkout the last commit that still has them.
+
+```shell
+cd nix-scripts
+git checkout c590df48e0553a670e18ebf9d02047bfcfddb40d
+cd ..
+```
+
 ## Setting up the environment and building firmware
 
 Within ``fish`` shell (others may not work correctly), set up the ARTIQ build environment:
@@ -54,8 +62,7 @@ artiq_flash -V <variant> -d artiq_kasli --srcbuild
 There's a slight discrepancy from usual command - ``-V <variant>`` option is not present in ARTIQ-7+, but it is necessary here.
 
 If you want to send the binaries to a customer, there's no need packing up the whole build directory - only `top.bit`, `bootloader.bin`
-and `runtime.elf/fbi` or `satman.elf/fbi` are necessary. You can use the `prep_pkg.py` script from extras to package 
-them up neatly into a zip file for distributions:
+and `runtime.elf/fbi` or `satman.elf/fbi` are necessary. You can use the `prep_pkg.py` script from extras to package them up neatly into a zip file for distributions:
 
 ```shell
 python prep_pkg.py -v <variant> -d artiq_kasli/

src/sw_sup/networking.md

@@ -8,8 +8,8 @@ a-la `I can't connect, please help`.
 1. `device_db.py` has misleading `core_addr` address.
 2. PC and the crate are in different subnets. They should be in the same network. Also you may want to directly attach the Kasli to the PC.
 3. Network restrictions/problems on your router, either by IP, MAC, protocols or anything else.
-4. Wrong configuration of the Kasli. Change IP or MAC address to correspond your network. For ARTIQ-8, add 
-   network mask to the `ip` setting on Kasli, like `192.168.1.75/24`.
+4. Wrong configuration of the Kasli. Change IP or MAC address to correspond your network. For ARTIQ-8 and later, add 
+   network mask to the `ip` setting on Kasli (not applicable for Kasli-SoC), like `192.168.1.75/24`.
 5. Incompatible Ethernet cables/SFP RJ45. Try different cables and SFP adapters. 
    We usually test them with CAT6 cables, but lower categories should be supported too.
 6. SFP or Ethernet are not pushed til the end.

src/sw_sup/setup_build_pc.md

@@ -33,7 +33,13 @@ by Vivado.
        }
     }
     ```
-4. Enable flakes in Nix by e.g. adding `experimental-features = nix-command flakes` to nix.conf (for example `~/.config/nix/nix.conf`).
+4. Enable flakes in Nix and add `/opt` to sandbox e.g. adding following to the `nix.conf` (for example `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`):
+    ```
+    experimental-features = nix-command flakes
+    extra-sandbox-paths = /opt
+    ```
+5. On Ubuntu, the Nix will conflict with Apparmor. You'll need to disable Apparmor for Nix, 
+   or for the whole system (you can also delete Apparmor completely, but be careful with it).
 
 From here, you should be able to enter ARTIQ development shell directly from URL, or by cloning the repository.
 The later will allow you to edit the source code in case of need.

src/sw_sup/uart_logs.md

@@ -15,6 +15,8 @@ until its fully loaded.
 
 ### Older Nix and other Linuxes
 
+Ensure your user is in `dialout` group.
+
 1. Install `cutecom` via `nix-shell -p cutecom` or your package manager
 2. Run `cutecom` and follow settings from the picture: ![uart_cutecom.png](../img/uart_cutecom.png)
 3. Restart the device with `artiq_flash start`, or by power-cycling it (wait 30 seconds before turning on)