Add afws instructions
Signed-off-by: Egor Savkin <es@m-labs.hk>
This commit is contained in:
parent
2777676057
commit
9a216f3d51
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
|
||||
Loading…
Reference in New Issue