linuswck/sinara-hw-assembly
1
0
Fork 0
forked from sinara-hw/assembly
Code Pull Requests Activity

Minor fixes in AFWS

Browse Source 
Signed-off-by: Egor Savkin <es@m-labs.hk>
This commit is contained in:
Egor Savkin 2024-06-20 16:56:35 +08:00
parent 9a216f3d51
commit d44be3dd8e
1 changed files with 19 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
src/sw_sup/afws_client.md
View File

@ -6,21 +6,21 @@ This article is intended to help with using the `afws_client` command properly.
### What is AFWS ### What is AFWS
AFWS (Artiq FirmWare Service) - a service, that allows building customer tailored firmware and gateware (binaries) on M-Labs's servers, 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 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, 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. or one-time when purchasing standalone cards for existing crate. Each variant/carrier requires its own subscription.
### What do I need for obtaining binaries ### What do I need for obtaining binaries
You'll need to have credentials - username and password, which you can obtain from helpdesk. 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. 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 ### 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. 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; 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.). 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. In such cases, these changes need to be authorized through helpdesk.
### How to ### How to
@ -33,22 +33,31 @@ afws_client <username> build <afws_directory> <variant>
Where (remove `<` and `>`): Where (remove `<` and `>`):
* `<username>` - your username from credentials * `<username>` - your username from credentials
* `<afws_directory>` - the directory/folder, into which you wish to save the binaries * `<afws_directory>` - the directory/folder, into which you wish to save the binaries
* `<variant>` - name of the crate/variant * `<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). 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), 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 AFWS will start building the firmware, which takes 10-15 minutes. Sometimes there might be some problems, in which
or AFWS service itself, in which cases you'll need to notify helpdesk. case don't hesitate to contact helpdesk.
After the build done, the AFWS client will automatically download the binaries into `<afws_directory>`, from which After the build done, the AFWS client will automatically download the binaries into `<afws_directory>`, from which
you can flash them into your Carrier. 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 #### Specify version
By default, AFWS client tries to figure out the installed ARTIQ version. However it works only for Kasli, and not Kasli-SoC. 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. 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. 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: In all these cases, you'll need to specify **both** `--major-ver` and `--rev` arguments, so your command will look like this:
```shell ```shell
afws_client <username> build --major-ver <MAJOR_VER> --rev <REV> <afws_directory> <variant> afws_client <username> build --major-ver <MAJOR_VER> --rev <REV> <afws_directory> <variant>
@ -72,8 +81,7 @@ The branches currently map as following:
* ARTIQ-9 - master * ARTIQ-9 - master
* ARTIQ-10 - nac3 * ARTIQ-10 - nac3
By some unfortunate technology/design choices, you need to specify both `--major-ver` and `--rev`. The binaries you receive are "pure" - if the inputs are the same (same version,
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 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). cache (e.g. not rebuilt).
@ -108,7 +116,8 @@ It will ask for password and output the variants and their respective expiry dat
#### Get JSONs #### Get JSONs
Sometimes you may want to view the JSON description, from which AFWS is building the variant. With the JSON, you can 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: 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 ```shell
afws_client <username> get_json [-o <OUT>] [-f] <variant> afws_client <username> get_json [-o <OUT>] [-f] <variant>