user_docs/Configuration and Operation.md

CTP7 Configuration and Operation

Basic Structure & Concepts

SD Card Layout

The CTP7 operates off of a MicroSD card.

The SD card must consist of three partitions:

Size Format Purpose
0 >=100Mb FAT Zynq Boot Image
1 Unused ext3 Presently Unused
2 Remaining ext3 Persistent Fileystem

root & user Accounts

The CTP7 is designed to operate with two separate accounts.

  • The root account

    This is a standard linux 'root' account. It should normally be used only for specific configuration that requires it, and not for general operation.

  • A standard user account

    This account is created by the first-use configuration tool. It is the account that the RPC service and any user-created linux tools should normally run as.

Persistent Configuration Storage

The CTP7 has a persistent SD filesystem located in /mnt/persistent, which contains all persistent user data and configuration, including non-root home directories. This area includes a directory called /mnt/persistent/config which contains specific persistent card configuration files, some of which are automatically managed.

Among these automatically managed files are: dropbear_*_host_key, group, passwd, root.authorized_keys. These files generally should not be updated directly. They should be updated with the save_passwd script discussed in Changing Passwords, and loaded automatically at startup.

Certain other files in this area may require manual modification and are discussed in the relevant sections.

First Use Configuration

Before Powerup

Before powering on a card, you must ensure that it has an appropriately structured SD card inserted. This card must be partitioned and formatted as explained above in the section on SD Card Layout, and the first (FAT) partition must contain a Zynq firmware file named BOOT.bin, which is provided with the CTP7.

First Run Configuration

On first startup with an uninitialized card and until the first run configuration is completed, a root password will be randomly assigned and printed on the console before the login prompt. Upon logging in as root for the first time, you will be prompted to change this password and create a standard user account for use as explained in root & user Accounts above. After completing this configuration and rebooting the linux system as instructed, the card will be ready for use and all available services will be active.

You must also complete the rpcsvc ACL Configuration described below to ensure that you can access the rpc service from all systems you intend to.

Secondary Standard User Accounts

If desired, you may also create alternate standard user accounts by running the following command. These accounts will generally function similarly to the primary one created by the first run configuration utility, but will not automatically have the ability to add rpcsvc modules (which run as the primary standard user account no matter their source), or replace the default bitstream. These capabilities are affected by standard linux filesystem permissions.

adduser -h /mnt/persistent/username username
save_passwd

General Configuration

Changing Passwords

To change account passwords, log in passwd. Following this, to save the changes to persistent storage, you must run save_passwd as root.

rpcsvc ACL Configuration

The rpcsvc only allows connections from a limited range of IP addresses by default. To configure the list of allowed IP ranges, you can edit the file /mnt/persistent/config/rpcsvc.acl.

This file contains a list of IP ranges that are allowed to access the rpcsvc in standard CIDR format, one per line.

Configuring the Default Startup Bitstream

On startup, the CTP7 will automatically configure the Virtex 7 clocks and load a provided bitstream. This occurs only on a power-on reset. In the case of any other type of reset, such as issuing the 'reboot' command to the linux system or a Zynq watchdog timeout, the Virtex 7 bitstream be unaffected and will remain configured and active.

Default Clock Configuration

The default Virtex 7 clock configuration is controlled by editing /mnt/persistent/config/clockinit_args, which contains an argument string to be supplied to the clockinit utility, described below in Configuring Clocks.

Default Bitstreams

The default Virtex 7 bitstream is loaded from /mnt/persistent/virtex7/virtex7.bin and may be either a bin or bit file. In the event that there is no file present there at all, the system will attempt to load a backup bitstream from /mnt/image/virtex7.bin. A basic blinky bitstream is provided in this location.

If the chosen image fails to load, the Virtex 7 will be left unconfigured and an error message will be printed on the console during boot. There is no automatic fallback in this case.

Custom Startup Scripts & Applications

All standard user accounts can execute commands or start custom services automatically on system startup by placing them in an executable shell script startup.sh in the user's home directory. This script will be run as the relevant user.

Note, it is recommended that you utilize the rpcsvc infrastructure where applicable, rather than writing custom services for external interaction with the card. See the provided rpcsvc client and module development packages for full examples.

Loading Bitstreams Manually

Configuring Clocks

To configure the Si5324 clock chips, you can use the command clockinit. The clockinit application takes several arguments:

clockinit freqA freqB be0_src be1_src fe1_src fe0_src

The first two parameters are frequency configurations for clock chip A and B. You may use any of several predefined frequencies (320_160, 128_192, or 250), or the path to a configuration file generated by the appropriate tool.

The following four parameters indicate the mapping of Si5324 outputs to Virtex 7 inputs. Pay careful attention to the order of parameters as it is 0 1 1 0, not 0 1 0 1. The values are A0 A1 B0 B1, indicating which clock chip (A or B) and which ouput from that clock chip (0 or 1) should supply the given input. A single output may supply as many or as few inputs as desired.

This command may be used from a standard user account.

Loading the Bitstream

To load a new bitstream into the Virtex 7, you may use the following command:

v7load /path/to/bitstream.bin

It accepts files in either bit or bin format, and will attempt to load the Virtex 7 and reinitialize the AXI Chip-2-Chip bridge. It is possible to deconfigure the Virtex 7 altogether by running v7load /dev/null, as this will cause v7load to deconfigure the FPGA and then fail to send it a new configuration.

This command may be used from a standard user account.

General Tools

mpeek & mpoke

There are mpeek and mpoke tools available for simple register accesses. These use the memsvc library documented in Compiling for Zynq to allow access to the Virtex 7 Chip-2-Chip memory space, and may be run as any user.

You can write to memory with mpoke 0x60000000 0x02c0ffee. It accepts an address and a data word in either decimal or hex format.

You can read from memory with mpeek 0x60000000. It accepts an address and prints the value at that address in hex format.

creset

It is possible for the root user to initiate a cold reset of the CTP7 playload, covering everything but the MMC and related systems by running the command creset. The linux will quiesce before initiating the cold reset.

quiesce

It is possible for any user to instruct the linux system to safely prepare for poweroff by executing the quiesce command. This will complete a safe unmount of all filesystems and leave the Zynq in a generally unusuable condition until it is reset. This quiesce sequence also occurs naturally when the card's hotswap handle is pulled, before the MMC authorizes deactivation of payload power.