From 9a216f3d51f17e4e521f714cf6ad47596b3c9bcb Mon Sep 17 00:00:00 2001 From: Egor Savkin Date: Thu, 20 Jun 2024 16:37:07 +0800 Subject: [PATCH] Add afws instructions Signed-off-by: Egor Savkin --- src/SUMMARY.md | 3 +- src/sw_sup/afws_client.md | 129 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 src/sw_sup/afws_client.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7cca166..4bd5f82 100644 --- a/src/SUMMARY.md +++ b/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) \ No newline at end of file + - [Setup your PC for building ARTIQ firmware](sw_sup/setup_build_pc.md) + - [AFWS client](sw_sup/afws_client.md) \ No newline at end of file diff --git a/src/sw_sup/afws_client.md b/src/sw_sup/afws_client.md new file mode 100644 index 0000000..7e426fc --- /dev/null +++ b/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 build +``` + +Where (remove `<` and `>`): +* `` - your username from credentials +* `` - the directory/folder, into which you wish to save the binaries +* `` - 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 ``, 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 build --major-ver --rev +``` + +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 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 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 get_json [-o ] [-f] +``` + +Specify output file `-o `, if you want to save it directly to file ``, 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) +