stabilizer: expand serial IO instruction

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

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/hw/mirny_almazny.md

@@ -8,9 +8,10 @@
 ```json
 {
   "type": "mirny",
-  "almazny": true, // for mirny with almazny only 
+  "almazny": true, // for mirny with almazny only
+  "almazny_hw_rev": "v1.2", // optional, must be provided for legacy (<=v1.1) Almazny
   "ports": [<port num>],
-  "clk_sel": 2, // optional
+  "clk_sel": "mmcx", // optional
   "refclk": 125e6 // optional
 }
 ```

src/hw/stabilizer.md

@@ -62,7 +62,7 @@ With newer firmware with USB serial console:
 
 1. Connect the Stabilizer to power.
 2. Connect USB cable to the Stabilizer.
-3. Connect with a serial console emulator, usually at ``/dev/ttyACM0``.
+3. Connect with a serial console emulator, for example ``python -m serial /dev/ttyACM0``.
 4. Input ``platform dfu`` in the console.
 
 And for both:

src/hw/zotino_fastino.md

@@ -16,6 +16,7 @@
 {
   "type": "fastino",
   "hw_rev": "v1.2", // optional
+  "log2_width": <0 to 5, default 0>, // pack multiple (in powers of 2) DAC channels into one RTIO write
   "ports": [<port num>]
 }
 ```

src/sw_sup/afws_client.md

@@ -91,8 +91,7 @@ After you received credentials from us, we strongly recommend changing the passw
 `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.
+Just keep in mind, that password may contain only alpha-numeric symbols and underscore `[a-zA-Z0-9_]`.
 If you cannot login, we may reset your password if you email us at helpdesk.
 
 #### Get variants

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,14 +8,15 @@ 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.
 7. Some weird bugs in Vivado, leading to not working SFP on certain combinations of builds and Kaslis (very rare)
 8. Running configured for external reference Kasli without external reference clock signal 
 9. Using legacy firmware with newer hardware. ARTIQ-6 doesn't support Kasli v2.0.2
+10. Some other device in your network already reserved the configured IP address.
 
 ## Ways to diagnose
 
@@ -27,6 +28,8 @@ a-la `I can't connect, please help`.
 5. `nmap` and `arp` to scan your network to help your Kasli get discovered. May be restricted in your network.
 6. Directly connect your Kasli to the PC via Ethernet and set up networking on the PC: `ip addr change 192.168.1.0/24 dev eth0`
 7. Become a router and capture all the packets when your Kasli tries to connect to the network.
+8. Turn off the Carrier/Kasli and `ping` the configured IP address. If it pings, then you'll need either set different
+   IP address on your Carrier or somehow deal with that other device - remove, assign different address, move to other network etc.
 
 
 ## Direct connection

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)