diff options
Diffstat (limited to 'Documentation/fmc/carrier.txt')
| -rw-r--r-- | Documentation/fmc/carrier.txt | 311 |
1 files changed, 0 insertions, 311 deletions
diff --git a/Documentation/fmc/carrier.txt b/Documentation/fmc/carrier.txt deleted file mode 100644 index 5e4f1dd3e98b..000000000000 --- a/Documentation/fmc/carrier.txt +++ /dev/null @@ -1,311 +0,0 @@ -FMC Device -********** - -Within the Linux bus framework, the FMC device is created and -registered by the carrier driver. For example, the PCI driver for the -SPEC card fills a data structure for each SPEC that it drives, and -registers an associated FMC device for each card. The SVEC driver can -do exactly the same for the VME carrier (actually, it should do it -twice, because the SVEC carries two FMC mezzanines). Similarly, an -Etherbone driver will be able to register its own FMC devices, offering -communication primitives through frame exchange. - -The contents of the EEPROM within the FMC are used for identification -purposes, i.e. for matching the device with its own driver. For this -reason the device structure includes a complete copy of the EEPROM -(actually, the carrier driver may choose whether or not to return it - -for example we most likely won't have the whole EEPROM available for -Etherbone devices. - -The following listing shows the current structure defining a device. -Please note that all the machinery is in place but some details may -still change in the future. For this reason, there is a version field -at the beginning of the structure. As usual, the minor number will -change for compatible changes (like a new flag) and the major number -will increase when an incompatible change happens (for example, a -change in layout of some fmc data structures). Device writers should -just set it to the value FMC_VERSION, and be ready to get back -EINVAL -at registration time. - - struct fmc_device { - unsigned long version; - unsigned long flags; - struct module *owner; /* char device must pin it */ - struct fmc_fru_id id; /* for EEPROM-based match */ - struct fmc_operations *op; /* carrier-provided */ - int irq; /* according to host bus. 0 == none */ - int eeprom_len; /* Usually 8kB, may be less */ - int eeprom_addr; /* 0x50, 0x52 etc */ - uint8_t *eeprom; /* Full contents or leading part */ - char *carrier_name; /* "SPEC" or similar, for special use */ - void *carrier_data; /* "struct spec *" or equivalent */ - __iomem void *fpga_base; /* May be NULL (Etherbone) */ - __iomem void *slot_base; /* Set by the driver */ - struct fmc_device **devarray; /* Allocated by the bus */ - int slot_id; /* Index in the slot array */ - int nr_slots; /* Number of slots in this carrier */ - unsigned long memlen; /* Used for the char device */ - struct device dev; /* For Linux use */ - struct device *hwdev; /* The underlying hardware device */ - unsigned long sdbfs_entry; - struct sdb_array *sdb; - uint32_t device_id; /* Filled by the device */ - char *mezzanine_name; /* Defaults to ``fmc'' */ - void *mezzanine_data; - }; - -The meaning of most fields is summarized in the code comment above. - -The following fields must be filled by the carrier driver before -registration: - - * version: must be set to FMC_VERSION. - - * owner: set to MODULE_OWNER. - - * op: the operations to act on the device. - - * irq: number for the mezzanine; may be zero. - - * eeprom_len: length of the following array. - - * eeprom_addr: 0x50 for first mezzanine and so on. - - * eeprom: the full content of the I2C EEPROM. - - * carrier_name. - - * carrier_data: a unique pointer for the carrier. - - * fpga_base: the I/O memory address (may be NULL). - - * slot_id: the index of this slot (starting from zero). - - * memlen: if fpga_base is valid, the length of I/O memory. - - * hwdev: to be used in some dev_err() calls. - - * device_id: a slot-specific unique integer number. - - -Please note that the carrier should read its own EEPROM memory before -registering the device, as well as fill all other fields listed above. - -The following fields should not be assigned, because they are filled -later by either the bus or the device driver: - - * flags. - - * fru_id: filled by the bus, parsing the eeprom. - - * slot_base: filled and used by the driver, if useful to it. - - * devarray: an array og all mezzanines driven by a singe FPGA. - - * nr_slots: set by the core at registration time. - - * dev: used by Linux. - - * sdb: FPGA contents, scanned according to driver's directions. - - * sdbfs_entry: SDB entry point in EEPROM: autodetected. - - * mezzanine_data: available for the driver. - - * mezzanine_name: filled by fmc-bus during identification. - - -Note: mezzanine_data may be redundant, because Linux offers the drvdata -approach, so the field may be removed in later versions of this bus -implementation. - -As I write this, she SPEC carrier is already completely functional in -the fmc-bus environment, and is a good reference to look at. - - -The API Offered by Carriers -=========================== - -The carrier provides a number of methods by means of the -`fmc_operations' structure, which currently is defined like this -(again, it is a moving target, please refer to the header rather than -this document): - - struct fmc_operations { - uint32_t (*readl)(struct fmc_device *fmc, int offset); - void (*writel)(struct fmc_device *fmc, uint32_t value, int offset); - int (*reprogram)(struct fmc_device *f, struct fmc_driver *d, char *gw); - int (*validate)(struct fmc_device *fmc, struct fmc_driver *drv); - int (*irq_request)(struct fmc_device *fmc, irq_handler_t h, - char *name, int flags); - void (*irq_ack)(struct fmc_device *fmc); - int (*irq_free)(struct fmc_device *fmc); - int (*gpio_config)(struct fmc_device *fmc, struct fmc_gpio *gpio, - int ngpio); - int (*read_ee)(struct fmc_device *fmc, int pos, void *d, int l); - int (*write_ee)(struct fmc_device *fmc, int pos, const void *d, int l); - }; - -The individual methods perform the following tasks: - -`readl' -`writel' - These functions access FPGA registers by whatever means the - carrier offers. They are not expected to fail, and most of the time - they will just make a memory access to the host bus. If the - carrier provides a fpga_base pointer, the driver may use direct - access through that pointer. For this reason the header offers the - inline functions fmc_readl and fmc_writel that access fpga_base if - the respective method is NULL. A driver that wants to be portable - and efficient should use fmc_readl and fmc_writel. For Etherbone, - or other non-local carriers, error-management is still to be - defined. - -`validate' - Module parameters are used to manage different applications for - two or more boards of the same kind. Validation is based on the - busid module parameter, if provided, and returns the matching - index in the associated array. See *note Module Parameters:: in in - doubt. If no match is found, `-ENOENT' is returned; if the user - didn't pass `busid=', all devices will pass validation. The value - returned by the validate method can be used as index into other - parameters (for example, some drivers use the `lm32=' parameter in - this way). Such "generic parameters" are documented in *note - Module Parameters::, below. The validate method is used by - `fmc-trivial.ko', described in *note fmc-trivial::. - -`reprogram' - The carrier enumerates FMC devices by loading a standard (or - golden) FPGA binary that allows EEPROM access. Each driver, then, - will need to reprogram the FPGA by calling this function. If the - name argument is NULL, the carrier should reprogram the golden - binary. If the gateware name has been overridden through module - parameters (in a carrier-specific way) the file loaded will match - the parameters. Per-device gateware names can be specified using - the `gateware=' parameter, see *note Module Parameters::. Note: - Clients should call rhe new helper, fmc_reprogram, which both - calls this method and parse the SDB tree of the FPGA. - -`irq_request' -`irq_ack' -`irq_free' - Interrupt management is carrier-specific, so it is abstracted as - operations. The interrupt number is listed in the device - structure, and for the mezzanine driver the number is only - informative. The handler will receive the fmc pointer as dev_id; - the flags argument is passed to the Linux request_irq function, - but fmc-specific flags may be added in the future. You'll most - likely want to pass the `IRQF_SHARED' flag. - -`gpio_config' - The method allows to configure a GPIO pin in the carrier, and read - its current value if it is configured as input. See *note The GPIO - Abstraction:: for details. - -`read_ee' -`write_ee' - Read or write the EEPROM. The functions are expected to be only - called before reprogramming and the carrier should refuse them - with `ENODEV' after reprogramming. The offset is expected to be - within 8kB (the current size), but addresses up to 1MB are - reserved to fit bigger I2C devices in the future. Carriers may - offer access to other internal flash memories using these same - methods: for example the SPEC driver may define that its carrier - I2C memory is seen at offset 1M and the internal SPI flash is seen - at offset 16M. This multiplexing of several flash memories in the - same address space is carrier-specific and should only be used - by a driver that has verified the `carrier_name' field. - - - -The GPIO Abstraction -==================== - -Support for GPIO pins in the fmc-bus environment is not very -straightforward and deserves special discussion. - -While the general idea of a carrier-independent driver seems to fly, -configuration of specific signals within the carrier needs at least -some knowledge of the carrier itself. For this reason, the specific -driver can request to configure carrier-specific GPIO pins, numbered -from 0 to at most 4095. Configuration is performed by passing a -pointer to an array of struct fmc_gpio items, as well as the length of -the array. This is the data structure: - - struct fmc_gpio { - char *carrier_name; - int gpio; - int _gpio; /* internal use by the carrier */ - int mode; /* GPIOF_DIR_OUT etc, from <linux/gpio.h> */ - int irqmode; /* IRQF_TRIGGER_LOW and so on */ - }; - -By specifying a carrier_name for each pin, the driver may access -different pins in different carriers. The gpio_config method is -expected to return the number of pins successfully configured, ignoring -requests for other carriers. However, if no pin is configured (because -no structure at all refers to the current carrier_name), the operation -returns an error so the caller will know that it is running under a -yet-unsupported carrier. - -So, for example, a driver that has been developed and tested on both -the SPEC and the SVEC may request configuration of two different GPIO -pins, and expect one such configuration to succeed - if none succeeds -it most likely means that the current carrier is a still-unknown one. - -If, however, your GPIO pin has a specific known role, you can pass a -special number in the gpio field, using one of the following macros: - - #define FMC_GPIO_RAW(x) (x) /* 4096 of them */ - #define FMC_GPIO_IRQ(x) ((x) + 0x1000) /* 256 of them */ - #define FMC_GPIO_LED(x) ((x) + 0x1100) /* 256 of them */ - #define FMC_GPIO_KEY(x) ((x) + 0x1200) /* 256 of them */ - #define FMC_GPIO_TP(x) ((x) + 0x1300) /* 256 of them */ - #define FMC_GPIO_USER(x) ((x) + 0x1400) /* 256 of them */ - -Use of virtual GPIO numbers (anything but FMC_GPIO_RAW) is allowed -provided the carrier_name field in the data structure is left -unspecified (NULL). Each carrier is responsible for providing a mapping -between virtual and physical GPIO numbers. The carrier may then use the -_gpio field to cache the result of this mapping. - -All carriers must map their I/O lines to the sets above starting from -zero. The SPEC, for example, maps interrupt pins 0 and 1, and test -points 0 through 3 (even if the test points on the PCB are called -5,6,7,8). - -If, for example, a driver requires a free LED and a test point (for a -scope probe to be plugged at some point during development) it may ask -for FMC_GPIO_LED(0) and FMC_GPIO_TP(0). Each carrier will provide -suitable GPIO pins. Clearly, the person running the drivers will know -the order used by the specific carrier driver in assigning leds and -testpoints, so to make a carrier-dependent use of the diagnostic tools. - -In theory, some form of autodetection should be possible: a driver like -the wr-nic (which uses IRQ(1) on the SPEC card) should configure -IRQ(0), make a test with software-generated interrupts and configure -IRQ(1) if the test fails. This probing step should be used because even -if the wr-nic gateware is known to use IRQ1 on the SPEC, the driver -should be carrier-independent and thus use IRQ(0) as a first bet - -actually, the knowledge that IRQ0 may fail is carrier-dependent -information, but using it doesn't make the driver unsuitable for other -carriers. - -The return value of gpio_config is defined as follows: - - * If no pin in the array can be used by the carrier, `-ENODEV'. - - * If at least one virtual GPIO number cannot be mapped, `-ENOENT'. - - * On success, 0 or positive. The value returned is the number of - high input bits (if no input is configured, the value for success - is 0). - -While I admit the procedure is not completely straightforward, it -allows configuration, input and output with a single carrier operation. -Given the typical use case of FMC devices, GPIO operations are not -expected to ever by in hot paths, and GPIO access so fare has only been -used to configure the interrupt pin, mode and polarity. Especially -reading inputs is not expected to be common. If your device has GPIO -capabilities in the hot path, you should consider using the kernel's -GPIO mechanisms. |