Dies ist eine alte Version des Dokuments!


PCI Express mit GPIO Interface

Einführung


Auf dieser Seite soll an einem Beispiel gezeigt werden wie GPIOs über eine PCIe Schnittstelle mit einem Linux Rechner angesteuert werden können. Das unten dargestellte Bild zeigt eine Übersicht über das gesamte System. Ein Linux Rechner ist über PCI Express (PCIe) mit einem FPGA verbunden. In diesem befindet sich zwei Blöcke einerseits der von Altera bereitgestellte IP Compiler und anderseits ein selbst geschriebener GPIO Block mit Avalon Interface.

GPIO Block


Als erstes soll genauer auf den GPIO Block eingegangen werden. Der Beispielcode kann hier heruntergeladen werden. Die folgende Signale bestimmen das Avalon Interface:

isl_clk :	IN STD_LOGIC;
isl_reset_n :	IN STD_LOGIC;
islv_avs_adress : IN STD_LOGIC_VECTOR(avs_adress_width_gpio_if-1 DOWNTO 0);
isl_avs_read :	IN STD_LOGIC;
isl_avs_write :	IN STD_LOGIC;
islv_avs_write_data : IN STD_LOGIC_VECTOR(avs_data_width_gpio_if-1 DOWNTO 0);
oslv_avs_read_data : OUT STD_LOGIC_VECTOR(avs_data_width_gpio_if-1 DOWNTO 0);

Dabei bestimmt die Konstante avs_adress_width_gpio_if die Anzahl Register des Blocks die angesprochen werden können. In diesem Beispiel ist der Wert 1 also können 2 Register angesprochen werden. Wird die Adressweite auf 2 gesetzt könne 4 Register angesprochen werden etc.
Die Konstante avs_data_width_gpio_if bestimmt die Breite der Register. Hier 64 Bit obwohl davon nur 16 verwendet werden. Dies erleichterst später den C-Code im Linux Treiber.
Die Daten vom Bus werden im folgend Codeabschnitt geschrieben:

IF isl_avs_write = '1' THEN
  CASE islv_avs_adress IS
    WHEN gpio_val_reg_address =>
      gpio_val_reg <= islv_avs_write_data(nr_of_gpios-1 DOWNTO 0);
    WHEN gpio_dir_reg_address =>		
      gpio_dir_reg <= islv_avs_write_data(nr_of_gpios-1 DOWNTO 0);
    WHEN OTHERS => null;		
  END CASE;
END IF;

Wenn also das write Signal high ist können je nach Wert des Adress Signals die Daten vom write_data Signal in einem anderen Register gespeichert werden.
Der Read-Teil funktioniert Analog dazu. Mit den gegeben Definitionen werden folgende Register bereitgestellt:

Offset: Grösse(Bit): Name: Richtung: Reset Wert: Funktion:
0 16 dir_reg RW 0x0000 1:GPIO Input, 0:GPIO Output
1 16 value_reg RW 0x0000 1:GPIO High, 0:GPIO Low

Danach müssen nur noch je nach Register Werten die Ausgänge gesetzt werden was mit folgendem Code gemacht werden kann:

FOR i IN 0 TO nr_of_gpios-1 LOOP
  IF gpio_dir_reg(i) = '0' THEN --output
    oslv_gpios(i) <= gpio_val_reg(i);
  ELSE --input
    oslv_gpios(i) <= 'Z';
    gpio_val_reg(i) <= oslv_gpios(i);
  END IF;
END LOOP;

GPIO Block in Qsys einbinden


Damit der erstellte Block in Qsys verwendet werden kann muss dieser dort eingebunden werden. Dazu in einem ersten Schritt in Quartus über Tools→Qsys Qsys starten und beim erscheinenden Dialog Feld auf Abbrechen klicken. Danach links oben einen Doppelklick auf New Component ausführen.


Im sich öffnenden Fenster wählt man im Register HDL Files alle für den Block benötigten Files aus.


Im Register Signals werden die vorhandenen Signal ihrer Funktion und ihrem Interface zugewiesen. Im hier beschriebenen Beispiele wird für das Signal isl_clk bei Interface New Clock Input.., für isl_reset_n New Reset Input.. und für das Signal oslv_gpios New Conduit.. ausgewählt. Für die übrigen Signale wählt man das bereits erstellt avalon_slave_0 aus. Danach muss noch die Spalte Signal Type ausgefüllt werden. Das ganze sollte dann so aussehen wie in der folgenden Abbildung:


Danach können mit einem klick auf Remove Interfaces With No Signals alle unnötigen Interfaces entfernt werden. Danach müssen beim avalon_slave_0 Interface die Clock und die Reset Quelle eingestellt werden. Ebenfalls bei der reset_sink muss ein Clock eingestellt werden. Damit sollten dann alle Fehlermeldungen unten im Fenster verschwunden sein.


Im Register Library Info können noch einige Paramter eingestellt werden wie zum Beispiel der Name der Komponente.


Mit Finish wird dann automatisch ein TCL Skript erstellt das im gleichen Ordner wie das Top File der Komponente abgelegt wird. Damit Qsys die erstellte Komponente beim erneuten Aufstarten wieder findet muss der Pfad unter Tools→Options noch eingetragen werden.


PCIe Block in Qsys erstellen


Wird in Qsys ein Doppelklick auf den \\IP_Compiler for PCI Express
ausgeführt wird eine Komponente zum System hinzugefügt. Im erscheinenden Fenster wählt man folgende Einstellungen:

System zusammenfügen


Mit einem Doppelklick auf die selbst geschriebenen Komponenten kann auch sie eingefügt werden. Alle Anderen Komponenten ausser der PCIe und den nun erschienen GPIO Komponenten können gelöscht werden. Danach müssen noch Verbindungen gezogen und bestimmt werden welche Singale Exportiert werden. Dies geschieht mit einem Klick auf \\Click to Export\\. Das fertige System sollte dann folgendermassen aussehen:


Wenn man nun unter System→Assign Base Addresses klickt sollten alle noch übrigen Error Meldungen verschwinden. Im Register Address Map kann man nun das Memory Map des Systems anschauen. Unter dem Register Generate kann mit dem Button Generate unten links das Generieren des Systems gestartet werden.

Einfügen des System in ein Design


Qsys erstellt beim Generieren des Systems automatisch ein Blocksymbol das dann in einem .bdf eingefügt werden kann. Ansonsten hat man auch die Möglichkeit das Design einfach als Komponente in einem VHDL File einzubinden. Damit das System korrekt arbeitet müssen die Ein- und Ausgänge folgendermassen gesetzt werden:

  • pcie_core_clk an einen 125Mhz Clock anschliessen.
  • refclk an die zwei differentiellen Pins des Referenz-Clocks des PCIe Bus anschliessen.
  • an den test_in Eingang konstant 0x00000000A8 anlegen. Die Bedeutung der einzelnen Bits kann dem Manual des PCIe IP Compiler entnommen werden.
  • pcie_rstn an den Reset Pin des PCIe Bus anschliessen.
  • rx_in an die zwei differentiellen RX_0 Pins des PCIe Bus anschliessen.
  • tx_out an die zwei differentiellen TX_0 Pins des PCIe Bus anschliessen.
  • reconfig_to_gxb konstant an 0x2 anschliessen dieser Wert kann wieder dem Manual entnommen werden.
  • reconfig_gxb_clk an GND anschliessen.
  • Die GPIO Ausgänge an beliebige Pins des FPGAs anschliessen.

Danach kann das System auf den FPGA geladen werden. Damit Linux das neue PCIe Device erkennt muss ein Neustart ausgeführt werden. Mit lspcie -v kann geprüft werden ob das System erkannt wurde.

Linux Kernel Modul


Damit die GPIOs aus dem User-Space z.B aus einem C Programm angesprochen werden können muss noch ein Kernel Modul geschrieben werden.
In diesem Modul wird in einem ersten Schritt nach dem PCIe Device gesucht:

#include <linux/pci.h>

static struct pci_dev *pci_device = NULL;

pci_device = pci_get_device(0x1172, 0x0004, NULL);
if (pci_device == NULL){
  //Error
}

Die beiden Parameter sind die Vendor- und Product ID des Devices die vorher in Qsys eingestellt wurden. Durch die Prüfung auf NULL kann festgestellt werden ob ein Device gefunden wurde. In einem nächsten Schritt wird das Device eingeschaltet:

error = pci_enable_device(pci_device);
if(error){
  //Error
}

Hat dies geklappt kann mit folgendem Befehl der Speicherbereich für dieses Modul reserviert werden. Damit wird verhindert, dass andere Modul ebenfalls Zugriff auf diesen Speicherbereich erhalten.

error = pci_request_regions(pci_device,KBUILD_MODNAME);
if(error){
  //Error		
}

Mit folgendem Befehl erhält man nun einen void Pointer auf den Speicherbereich:

//Io map base address
base_addr = pci_iomap(pci_device,0,0);
if (base_addr == NULL){
  //Error
}

Mit diesen hat man nun beliebig Zugriff auf die Register des FPGAs. Der zweite Parameter gibt an welche Memory-Bar man gerne hätte. Würde man dort z.B. 2 wählen erhält man einen Pointer auf das Config Register des PCIe Blocks. Im Fall des GPIO's Moduls könnte man z.B nun ein RTDM Echtzeitdevice erstellen. Hier ein Beispiel für die Header Datei:

#include <rtdm/rttesting.h>
#include <rtdm/rtdm_driver.h>

int init_fpga_gpio(void *bPtr);
void cleanup_fpga_gpio(void);
int fpga_gpio_open(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, int oflags);
int fpga_gpio_close(struct rtdm_dev_context *context, rtdm_user_info_t *user_info);
int fpga_gpio_read(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, void *buf, size_t nbyte);
int fpga_gpio_write(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, const void *buf, size_t nbyte);
int fpga_gpio_ioctr(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, unsigned int request, void __user *arg);

static struct rtdm_device fpgaGPIODevice =
{
	.struct_version    = RTDM_DEVICE_STRUCT_VER,

	.device_name       = FPGA_GPIO_DEVICE_NAME,
	.device_flags      = RTDM_NAMED_DEVICE,
	.context_size      = 0,

	.open_nrt = fpga_gpio_open,

	.ops = {
		.close_nrt = fpga_gpio_close,
		.read_rt  = fpga_gpio_read,
		.read_nrt  = fpga_gpio_read,
		.write_rt = fpga_gpio_write,
		.write_nrt = fpga_gpio_write,
		.ioctl_rt = fpga_gpio_ioctr,
		.ioctl_nrt = fpga_gpio_ioctr,
	},

	.device_class      = RTDM_CLASS_TESTING,
	.driver_name       = "fpgaGPIO",
	.driver_version    = RTDM_DRIVER_VER(0, 1, 1),
	.peripheral_name   = "FPGA_GPIO",
	.provider_name     = "www.ntb.ch",
	.proc_name         = fpgaGPIODevice.device_name,
};

Dann im C-File wird in der Init Methode der Base-Pointer auf einen unsigned long long gesetzt damit bei einem Inkrement des Pointer die Adresse um 64Bit weiter springt so wie es im Avalon Interface Definiert wurde. Weiter wird das Device im System registriert:

static unsigned long long *gpioBasePtr = NULL;

int init_fpga_gpio(void *bPtr){
  gpioBasePtr = ((unsigned long long*) bPtr) + GPIO_INTERFACE_OFFSET;
  if(rtdm_dev_register(&fpgaGPIODevice)){
    printk( KERN_ERR "PCIe_TO_FPGA: register gpio device driver error\n");
    return -1;
  }
  return 0;
}

In der Write Methode kann nun z.B. der Wert der GPIO's geschrieben werden:

int fpga_gpio_write(struct rtdm_dev_context *context, rtdm_user_info_t *user_info, const void *buf, size_t nbyte){
  iowrite16(((unsigned short*)buf)[0],gpioBasePtr+GPIO_VALUE_REG_OFFSET);
  return nbyte;
}