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.