Add afws 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/sw_sup/afws_client.md

@@ -0,0 +1,129 @@
+# 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. 
+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
+
+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 problems with the configuration
+or AFWS service itself, in which cases you'll need to notify 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.
+
+#### 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
+
+By some unfortunate technology/design choices, you need to specify both `--major-ver` and `--rev`. 
+From other side, you may be sure that 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 (e.g. 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:
+
+```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)
+