aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/00-INDEX2
-rw-r--r--Documentation/devicetree/bindings/ata/atmel-at91_cf.txt19
-rw-r--r--Documentation/devicetree/bindings/extcon/extcon-twl.txt15
-rw-r--r--Documentation/devicetree/bindings/memory-controllers/mvebu-devbus.txt156
-rw-r--r--Documentation/fmc/00-INDEX38
-rw-r--r--Documentation/fmc/API.txt47
-rw-r--r--Documentation/fmc/FMC-and-SDB.txt88
-rw-r--r--Documentation/fmc/carrier.txt311
-rw-r--r--Documentation/fmc/fmc-chardev.txt64
-rw-r--r--Documentation/fmc/fmc-fakedev.txt36
-rw-r--r--Documentation/fmc/fmc-trivial.txt17
-rw-r--r--Documentation/fmc/fmc-write-eeprom.txt125
-rw-r--r--Documentation/fmc/identifiers.txt168
-rw-r--r--Documentation/fmc/mezzanine.txt123
-rw-r--r--Documentation/fmc/parameters.txt56
-rw-r--r--Documentation/w1/w1.generic4
16 files changed, 1267 insertions, 2 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 45b3df936d2f..0c4cc688e89a 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -187,6 +187,8 @@ firmware_class/
187 - request_firmware() hotplug interface info. 187 - request_firmware() hotplug interface info.
188flexible-arrays.txt 188flexible-arrays.txt
189 - how to make use of flexible sized arrays in linux 189 - how to make use of flexible sized arrays in linux
190fmc/
191 - information about the FMC bus abstraction
190frv/ 192frv/
191 - Fujitsu FR-V Linux documentation. 193 - Fujitsu FR-V Linux documentation.
192futex-requeue-pi.txt 194futex-requeue-pi.txt
diff --git a/Documentation/devicetree/bindings/ata/atmel-at91_cf.txt b/Documentation/devicetree/bindings/ata/atmel-at91_cf.txt
new file mode 100644
index 000000000000..c1d22b3ae134
--- /dev/null
+++ b/Documentation/devicetree/bindings/ata/atmel-at91_cf.txt
@@ -0,0 +1,19 @@
1Atmel AT91RM9200 CompactFlash
2
3Required properties:
4- compatible : "atmel,at91rm9200-cf".
5- reg : should specify localbus address and size used.
6- gpios : specifies the gpio pins to control the CF device. Detect
7 and reset gpio's are mandatory while irq and vcc gpio's are
8 optional and may be set to 0 if not present.
9
10Example:
11compact-flash@50000000 {
12 compatible = "atmel,at91rm9200-cf";
13 reg = <0x50000000 0x30000000>;
14 gpios = <&pioC 13 0 /* irq */
15 &pioC 15 0 /* detect */
16 0 /* vcc */
17 &pioC 5 0 /* reset */
18 >;
19};
diff --git a/Documentation/devicetree/bindings/extcon/extcon-twl.txt b/Documentation/devicetree/bindings/extcon/extcon-twl.txt
new file mode 100644
index 000000000000..58f531ab4df3
--- /dev/null
+++ b/Documentation/devicetree/bindings/extcon/extcon-twl.txt
@@ -0,0 +1,15 @@
1EXTCON FOR TWL CHIPS
2
3PALMAS USB COMPARATOR
4Required Properties:
5 - compatible : Should be "ti,palmas-usb" or "ti,twl6035-usb"
6 - vbus-supply : phandle to the regulator device tree node.
7
8Optional Properties:
9 - ti,wakeup : To enable the wakeup comparator in probe
10
11palmas-usb {
12 compatible = "ti,twl6035-usb", "ti,palmas-usb";
13 vbus-supply = <&smps10_reg>;
14 ti,wakeup;
15};
diff --git a/Documentation/devicetree/bindings/memory-controllers/mvebu-devbus.txt b/Documentation/devicetree/bindings/memory-controllers/mvebu-devbus.txt
new file mode 100644
index 000000000000..653c90c34a71
--- /dev/null
+++ b/Documentation/devicetree/bindings/memory-controllers/mvebu-devbus.txt
@@ -0,0 +1,156 @@
1Device tree bindings for MVEBU Device Bus controllers
2
3The Device Bus controller available in some Marvell's SoC allows to control
4different types of standard memory and I/O devices such as NOR, NAND, and FPGA.
5The actual devices are instantiated from the child nodes of a Device Bus node.
6
7Required properties:
8
9 - compatible: Currently only Armada 370/XP SoC are supported,
10 with this compatible string:
11
12 marvell,mvebu-devbus
13
14 - reg: A resource specifier for the register space.
15 This is the base address of a chip select within
16 the controller's register space.
17 (see the example below)
18
19 - #address-cells: Must be set to 1
20 - #size-cells: Must be set to 1
21 - ranges: Must be set up to reflect the memory layout with four
22 integer values for each chip-select line in use:
23 0 <physical address of mapping> <size>
24
25Mandatory timing properties for child nodes:
26
27Read parameters:
28
29 - devbus,turn-off-ps: Defines the time during which the controller does not
30 drive the AD bus after the completion of a device read.
31 This prevents contentions on the Device Bus after a read
32 cycle from a slow device.
33
34 - devbus,bus-width: Defines the bus width (e.g. <16>)
35
36 - devbus,badr-skew-ps: Defines the time delay from from A[2:0] toggle,
37 to read data sample. This parameter is useful for
38 synchronous pipelined devices, where the address
39 precedes the read data by one or two cycles.
40
41 - devbus,acc-first-ps: Defines the time delay from the negation of
42 ALE[0] to the cycle that the first read data is sampled
43 by the controller.
44
45 - devbus,acc-next-ps: Defines the time delay between the cycle that
46 samples data N and the cycle that samples data N+1
47 (in burst accesses).
48
49 - devbus,rd-setup-ps: Defines the time delay between DEV_CSn assertion to
50 DEV_OEn assertion. If set to 0 (default),
51 DEV_OEn and DEV_CSn are asserted at the same cycle.
52 This parameter has no affect on <acc-first-ps> parameter
53 (no affect on first data sample). Set <rd-setup-ps>
54 to a value smaller than <acc-first-ps>.
55
56 - devbus,rd-hold-ps: Defines the time between the last data sample to the
57 de-assertion of DEV_CSn. If set to 0 (default),
58 DEV_OEn and DEV_CSn are de-asserted at the same cycle
59 (the cycle of the last data sample).
60 This parameter has no affect on DEV_OEn de-assertion.
61 DEV_OEn is always de-asserted the next cycle after
62 last data sampled. Also this parameter has no
63 affect on <turn-off-ps> parameter.
64 Set <rd-hold-ps> to a value smaller than <turn-off-ps>.
65
66Write parameters:
67
68 - devbus,ale-wr-ps: Defines the time delay from the ALE[0] negation cycle
69 to the DEV_WEn assertion.
70
71 - devbus,wr-low-ps: Defines the time during which DEV_WEn is active.
72 A[2:0] and Data are kept valid as long as DEV_WEn
73 is active. This parameter defines the setup time of
74 address and data to DEV_WEn rise.
75
76 - devbus,wr-high-ps: Defines the time during which DEV_WEn is kept
77 inactive (high) between data beats of a burst write.
78 DEV_A[2:0] and Data are kept valid (do not toggle) for
79 <wr-high-ps> - <tick> ps.
80 This parameter defines the hold time of address and
81 data after DEV_WEn rise.
82
83 - devbus,sync-enable: Synchronous device enable.
84 1: True
85 0: False
86
87An example for an Armada XP GP board, with a 16 MiB NOR device as child
88is showed below. Note that the Device Bus driver is in charge of allocating
89the mbus address decoding window for each of its child devices.
90The window is created using the chip select specified in the child
91device node together with the base address and size specified in the ranges
92property. For instance, in the example below the allocated decoding window
93will start at base address 0xf0000000, with a size 0x1000000 (16 MiB)
94for chip select 0 (a.k.a DEV_BOOTCS).
95
96This address window handling is done in this mvebu-devbus only as a temporary
97solution. It will be removed when the support for mbus device tree binding is
98added.
99
100The reg property implicitly specifies the chip select as this:
101
102 0x10400: DEV_BOOTCS
103 0x10408: DEV_CS0
104 0x10410: DEV_CS1
105 0x10418: DEV_CS2
106 0x10420: DEV_CS3
107
108Example:
109
110 devbus-bootcs@d0010400 {
111 status = "okay";
112 ranges = <0 0xf0000000 0x1000000>; /* @addr 0xf0000000, size 0x1000000 */
113 #address-cells = <1>;
114 #size-cells = <1>;
115
116 /* Device Bus parameters are required */
117
118 /* Read parameters */
119 devbus,bus-width = <8>;
120 devbus,turn-off-ps = <60000>;
121 devbus,badr-skew-ps = <0>;
122 devbus,acc-first-ps = <124000>;
123 devbus,acc-next-ps = <248000>;
124 devbus,rd-setup-ps = <0>;
125 devbus,rd-hold-ps = <0>;
126
127 /* Write parameters */
128 devbus,sync-enable = <0>;
129 devbus,wr-high-ps = <60000>;
130 devbus,wr-low-ps = <60000>;
131 devbus,ale-wr-ps = <60000>;
132
133 flash@0 {
134 compatible = "cfi-flash";
135
136 /* 16 MiB */
137 reg = <0 0x1000000>;
138 bank-width = <2>;
139 #address-cells = <1>;
140 #size-cells = <1>;
141
142 /*
143 * We split the 16 MiB in two partitions,
144 * just as an example.
145 */
146 partition@0 {
147 label = "First";
148 reg = <0 0x800000>;
149 };
150
151 partition@800000 {
152 label = "Second";
153 reg = <0x800000 0x800000>;
154 };
155 };
156 };
diff --git a/Documentation/fmc/00-INDEX b/Documentation/fmc/00-INDEX
new file mode 100644
index 000000000000..431c69570f43
--- /dev/null
+++ b/Documentation/fmc/00-INDEX
@@ -0,0 +1,38 @@
1
2Documentation in this directory comes from sections of the manual we
3wrote for the externally-developed fmc-bus package. The complete
4manual as of today (2013-02) is available in PDF format at
5http://www.ohwr.org/projects/fmc-bus/files
6
700-INDEX
8 - this file.
9
10FMC-and-SDB.txt
11 - What are FMC and SDB, basic concepts for this framework
12
13API.txt
14 - The functions that are exported by the bus driver
15
16parameters.txt
17 - The module parameters
18
19carrier.txt
20 - writing a carrier (a device)
21
22mezzanine.txt
23 - writing code for your mezzanine (a driver)
24
25identifiers.txt
26 - how identification and matching works
27
28fmc-fakedev.txt
29 - about drivers/fmc/fmc-fakedev.ko
30
31fmc-trivial.txt
32 - about drivers/fmc/fmc-trivial.ko
33
34fmc-write-eeprom.txt
35 - about drivers/fmc/fmc-write-eeprom.ko
36
37fmc-chardev.txt
38 - about drivers/fmc/fmc-chardev.ko
diff --git a/Documentation/fmc/API.txt b/Documentation/fmc/API.txt
new file mode 100644
index 000000000000..06b06b92c794
--- /dev/null
+++ b/Documentation/fmc/API.txt
@@ -0,0 +1,47 @@
1Functions Exported by fmc.ko
2****************************
3
4The FMC core exports the usual 4 functions that are needed for a bus to
5work, and a few more:
6
7 int fmc_driver_register(struct fmc_driver *drv);
8 void fmc_driver_unregister(struct fmc_driver *drv);
9 int fmc_device_register(struct fmc_device *fmc);
10 void fmc_device_unregister(struct fmc_device *fmc);
11
12 int fmc_device_register_n(struct fmc_device **fmc, int n);
13 void fmc_device_unregister_n(struct fmc_device **fmc, int n);
14
15 uint32_t fmc_readl(struct fmc_device *fmc, int offset);
16 void fmc_writel(struct fmc_device *fmc, uint32_t val, int off);
17 void *fmc_get_drvdata(struct fmc_device *fmc);
18 void fmc_set_drvdata(struct fmc_device *fmc, void *data);
19
20 int fmc_reprogram(struct fmc_device *f, struct fmc_driver *d, char *gw,
21 int sdb_entry);
22
23The data structure that describe a device is detailed in *note FMC
24Device::, the one that describes a driver is detailed in *note FMC
25Driver::. Please note that structures of type fmc_device must be
26allocated by the caller, but must not be released after unregistering.
27The fmc-bus itself takes care of releasing the structure when their use
28count reaches zero - actually, the device model does that in lieu of us.
29
30The functions to register and unregister n devices are meant to be used
31by carriers that host more than one mezzanine. The devices must all be
32registered at the same time because if the FPGA is reprogrammed, all
33devices in the array are affected. Usually, the driver matching the
34first device will reprogram the FPGA, so other devices must know they
35are already driven by a reprogrammed FPGA.
36
37If a carrier hosts slots that are driven by different FPGA devices, it
38should register as a group only mezzanines that are driven by the same
39FPGA, for the reason outlined above.
40
41Finally, the fmc_reprogram function calls the reprogram method (see
42*note The API Offered by Carriers:: and also scans the memory area for
43an SDB tree. You can pass -1 as sdb_entry to disable such scan.
44Otherwise, the function fails if no tree is found at the specified
45entry point. The function is meant to factorize common code, and by
46the time you read this it is already used by the spec-sw and fine-delay
47modules.
diff --git a/Documentation/fmc/FMC-and-SDB.txt b/Documentation/fmc/FMC-and-SDB.txt
new file mode 100644
index 000000000000..fa14e0b24521
--- /dev/null
+++ b/Documentation/fmc/FMC-and-SDB.txt
@@ -0,0 +1,88 @@
1
2FMC (FPGA Mezzanine Card) is the standard we use for our I/O devices,
3in the context of White Rabbit and related hardware.
4
5In our I/O environments we need to write drivers for each mezzanine
6card, and such drivers must work regardless of the carrier being used.
7To achieve this, we abstract the FMC interface.
8
9We have a carrier for PCI-E called SPEC and one for VME called SVEC,
10but more are planned. Also, we support stand-alone devices (usually
11plugged on a SPEC card), controlled through Etherbone, developed by GSI.
12
13Code and documentation for the FMC bus was born as part of the spec-sw
14project, but now it lives in its own project. Other projects, i.e.
15software support for the various carriers, should include this as a
16submodule.
17
18The most up to date version of code and documentation is always
19available from the repository you can clone from:
20
21 git://ohwr.org/fmc-projects/fmc-bus.git (read-only)
22 git@ohwr.org:fmc-projects/fmc-bus.git (read-write for developers)
23
24Selected versions of the documentation, as well as complete tar
25archives for selected revisions are placed to the Files section of the
26project: `http://www.ohwr.org/projects/fmc-bus/files'
27
28
29What is FMC
30***********
31
32FMC, as said, stands for "FPGA Mezzanine Card". It is a standard
33developed by the VME consortium called VITA (VMEbus International Trade
34Association and ratified by ANSI, the American National Standard
35Institute. The official documentation is called "ANSI-VITA 57.1".
36
37The FMC card is an almost square PCB, around 70x75 millimeters, that is
38called mezzanine in this document. It usually lives plugged into
39another PCB for power supply and control; such bigger circuit board is
40called carrier from now on, and a single carrier may host more than one
41mezzanine.
42
43In the typical application the mezzanine is mostly analog while the
44carrier is mostly digital, and hosts an FPGA that must be configured to
45match the specific mezzanine and the desired application. Thus, you may
46need to load different FPGA images to drive different instances of the
47same mezzanine.
48
49FMC, as such, is not a bus in the usual meaning of the term, because
50most carriers have only one connector, and carriers with several
51connectors have completely separate electrical connections to them.
52This package, however, implements a bus as a software abstraction.
53
54
55What is SDB
56***********
57
58SDB (Self Describing Bus) is a set of data structures that we use for
59enumerating the internal structure of an FPGA image. We also use it as
60a filesystem inside the FMC EEPROM.
61
62SDB is not mandatory for use of this FMC kernel bus, but if you have SDB
63this package can make good use of it. SDB itself is developed in the
64fpga-config-space OHWR project. The link to the repository is
65`git://ohwr.org/hdl-core-lib/fpga-config-space.git' and what is used in
66this project lives in the sdbfs subdirectory in there.
67
68SDB support for FMC is described in *note FMC Identification:: and
69*note SDB Support::
70
71
72SDB Support
73***********
74
75The fmc.ko bus driver exports a few functions to help drivers taking
76advantage of the SDB information that may be present in your own FPGA
77memory image.
78
79The module exports the following functions, in the special header
80<linux/fmc-sdb.h>. The linux/ prefix in the name is there because we
81plan to submit it upstream in the future, and don't want to force
82changes on our drivers if that happens.
83
84 int fmc_scan_sdb_tree(struct fmc_device *fmc, unsigned long address);
85 void fmc_show_sdb_tree(struct fmc_device *fmc);
86 signed long fmc_find_sdb_device(struct sdb_array *tree, uint64_t vendor,
87 uint32_t device, unsigned long *sz);
88 int fmc_free_sdb_tree(struct fmc_device *fmc);
diff --git a/Documentation/fmc/carrier.txt b/Documentation/fmc/carrier.txt
new file mode 100644
index 000000000000..173f6d65c88d
--- /dev/null
+++ b/Documentation/fmc/carrier.txt
@@ -0,0 +1,311 @@
1FMC Device
2**********
3
4Within the Linux bus framework, the FMC device is created and
5registered by the carrier driver. For example, the PCI driver for the
6SPEC card fills a data structure for each SPEC that it drives, and
7registers an associated FMC device for each card. The SVEC driver can
8do exactly the same for the VME carrier (actually, it should do it
9twice, because the SVEC carries two FMC mezzanines). Similarly, an
10Etherbone driver will be able to register its own FMC devices, offering
11communication primitives through frame exchange.
12
13The contents of the EEPROM within the FMC are used for identification
14purposes, i.e. for matching the device with its own driver. For this
15reason the device structure includes a complete copy of the EEPROM
16(actually, the carrier driver may choose whether or not to return it -
17for example we most likely won't have the whole EEPROM available for
18Etherbone devices.
19
20The following listing shows the current structure defining a device.
21Please note that all the machinery is in place but some details may
22still change in the future. For this reason, there is a version field
23at the beginning of the structure. As usual, the minor number will
24change for compatible changes (like a new flag) and the major number
25will increase when an incompatible change happens (for example, a
26change in layout of some fmc data structures). Device writers should
27just set it to the value FMC_VERSION, and be ready to get back -EINVAL
28at registration time.
29
30 struct fmc_device {
31 unsigned long version;
32 unsigned long flags;
33 struct module *owner; /* char device must pin it */
34 struct fmc_fru_id id; /* for EEPROM-based match */
35 struct fmc_operations *op; /* carrier-provided */
36 int irq; /* according to host bus. 0 == none */
37 int eeprom_len; /* Usually 8kB, may be less */
38 int eeprom_addr; /* 0x50, 0x52 etc */
39 uint8_t *eeprom; /* Full contents or leading part */
40 char *carrier_name; /* "SPEC" or similar, for special use */
41 void *carrier_data; /* "struct spec *" or equivalent */
42 __iomem void *fpga_base; /* May be NULL (Etherbone) */
43 __iomem void *slot_base; /* Set by the driver */
44 struct fmc_device **devarray; /* Allocated by the bus */
45 int slot_id; /* Index in the slot array */
46 int nr_slots; /* Number of slots in this carrier */
47 unsigned long memlen; /* Used for the char device */
48 struct device dev; /* For Linux use */
49 struct device *hwdev; /* The underlying hardware device */
50 unsigned long sdbfs_entry;
51 struct sdb_array *sdb;
52 uint32_t device_id; /* Filled by the device */
53 char *mezzanine_name; /* Defaults to ``fmc'' */
54 void *mezzanine_data;
55 };
56
57The meaning of most fields is summarized in the code comment above.
58
59The following fields must be filled by the carrier driver before
60registration:
61
62 * version: must be set to FMC_VERSION.
63
64 * owner: set to MODULE_OWNER.
65
66 * op: the operations to act on the device.
67
68 * irq: number for the mezzanine; may be zero.
69
70 * eeprom_len: length of the following array.
71
72 * eeprom_addr: 0x50 for first mezzanine and so on.
73
74 * eeprom: the full content of the I2C EEPROM.
75
76 * carrier_name.
77
78 * carrier_data: a unique pointer for the carrier.
79
80 * fpga_base: the I/O memory address (may be NULL).
81
82 * slot_id: the index of this slot (starting from zero).
83
84 * memlen: if fpga_base is valid, the length of I/O memory.
85
86 * hwdev: to be used in some dev_err() calls.
87
88 * device_id: a slot-specific unique integer number.
89
90
91Please note that the carrier should read its own EEPROM memory before
92registering the device, as well as fill all other fields listed above.
93
94The following fields should not be assigned, because they are filled
95later by either the bus or the device driver:
96
97 * flags.
98
99 * fru_id: filled by the bus, parsing the eeprom.
100
101 * slot_base: filled and used by the driver, if useful to it.
102
103 * devarray: an array og all mezzanines driven by a singe FPGA.
104
105 * nr_slots: set by the core at registration time.
106
107 * dev: used by Linux.
108
109 * sdb: FPGA contents, scanned according to driver's directions.
110
111 * sdbfs_entry: SDB entry point in EEPROM: autodetected.
112
113 * mezzanine_data: available for the driver.
114
115 * mezzanine_name: filled by fmc-bus during identification.
116
117
118Note: mezzanine_data may be redundant, because Linux offers the drvdata
119approach, so the field may be removed in later versions of this bus
120implementation.
121
122As I write this, she SPEC carrier is already completely functional in
123the fmc-bus environment, and is a good reference to look at.
124
125
126The API Offered by Carriers
127===========================
128
129The carrier provides a number of methods by means of the
130`fmc_operations' structure, which currently is defined like this
131(again, it is a moving target, please refer to the header rather than
132this document):
133
134 struct fmc_operations {
135 uint32_t (*readl)(struct fmc_device *fmc, int offset);
136 void (*writel)(struct fmc_device *fmc, uint32_t value, int offset);
137 int (*reprogram)(struct fmc_device *f, struct fmc_driver *d, char *gw);
138 int (*validate)(struct fmc_device *fmc, struct fmc_driver *drv);
139 int (*irq_request)(struct fmc_device *fmc, irq_handler_t h,
140 char *name, int flags);
141 void (*irq_ack)(struct fmc_device *fmc);
142 int (*irq_free)(struct fmc_device *fmc);
143 int (*gpio_config)(struct fmc_device *fmc, struct fmc_gpio *gpio,
144 int ngpio);
145 int (*read_ee)(struct fmc_device *fmc, int pos, void *d, int l);
146 int (*write_ee)(struct fmc_device *fmc, int pos, const void *d, int l);
147 };
148
149The individual methods perform the following tasks:
150
151`readl'
152`writel'
153 These functions access FPGA registers by whatever means the
154 carrier offers. They are not expected to fail, and most of the time
155 they will just make a memory access to the host bus. If the
156 carrier provides a fpga_base pointer, the driver may use direct
157 access through that pointer. For this reason the header offers the
158 inline functions fmc_readl and fmc_writel that access fpga_base if
159 the respective method is NULL. A driver that wants to be portable
160 and efficient should use fmc_readl and fmc_writel. For Etherbone,
161 or other non-local carriers, error-management is still to be
162 defined.
163
164`validate'
165 Module parameters are used to manage different applications for
166 two or more boards of the same kind. Validation is based on the
167 busid module parameter, if provided, and returns the matching
168 index in the associated array. See *note Module Parameters:: in in
169 doubt. If no match is found, `-ENOENT' is returned; if the user
170 didn't pass `busid=', all devices will pass validation. The value
171 returned by the validate method can be used as index into other
172 parameters (for example, some drivers use the `lm32=' parameter in
173 this way). Such "generic parameters" are documented in *note
174 Module Parameters::, below. The validate method is used by
175 `fmc-trivial.ko', described in *note fmc-trivial::.
176
177`reprogram'
178 The carrier enumerates FMC devices by loading a standard (or
179 golden) FPGA binary that allows EEPROM access. Each driver, then,
180 will need to reprogram the FPGA by calling this function. If the
181 name argument is NULL, the carrier should reprogram the golden
182 binary. If the gateware name has been overridden through module
183 parameters (in a carrier-specific way) the file loaded will match
184 the parameters. Per-device gateware names can be specified using
185 the `gateware=' parameter, see *note Module Parameters::. Note:
186 Clients should call rhe new helper, fmc_reprogram, which both
187 calls this method and parse the SDB tree of the FPGA.
188
189`irq_request'
190`irq_ack'
191`irq_free'
192 Interrupt management is carrier-specific, so it is abstracted as
193 operations. The interrupt number is listed in the device
194 structure, and for the mezzanine driver the number is only
195 informative. The handler will receive the fmc pointer as dev_id;
196 the flags argument is passed to the Linux request_irq function,
197 but fmc-specific flags may be added in the future. You'll most
198 likely want to pass the `IRQF_SHARED' flag.
199
200`gpio_config'
201 The method allows to configure a GPIO pin in the carrier, and read
202 its current value if it is configured as input. See *note The GPIO
203 Abstraction:: for details.
204
205`read_ee'
206`write_ee'
207 Read or write the EEPROM. The functions are expected to be only
208 called before reprogramming and the carrier should refuse them
209 with `ENODEV' after reprogramming. The offset is expected to be
210 within 8kB (the current size), but addresses up to 1MB are
211 reserved to fit bigger I2C devices in the future. Carriers may
212 offer access to other internal flash memories using these same
213 methods: for example the SPEC driver may define that its carrier
214 I2C memory is seen at offset 1M and the internal SPI flash is seen
215 at offset 16M. This multiplexing of several flash memories in the
216 same address space is is carrier-specific and should only be used
217 by a driver that has verified the `carrier_name' field.
218
219
220
221The GPIO Abstraction
222====================
223
224Support for GPIO pins in the fmc-bus environment is not very
225straightforward and deserves special discussion.
226
227While the general idea of a carrier-independent driver seems to fly,
228configuration of specific signals within the carrier needs at least
229some knowledge of the carrier itself. For this reason, the specific
230driver can request to configure carrier-specific GPIO pins, numbered
231from 0 to at most 4095. Configuration is performed by passing a
232pointer to an array of struct fmc_gpio items, as well as the length of
233the array. This is the data structure:
234
235 struct fmc_gpio {
236 char *carrier_name;
237 int gpio;
238 int _gpio; /* internal use by the carrier */
239 int mode; /* GPIOF_DIR_OUT etc, from <linux/gpio.h> */
240 int irqmode; /* IRQF_TRIGGER_LOW and so on */
241 };
242
243By specifying a carrier_name for each pin, the driver may access
244different pins in different carriers. The gpio_config method is
245expected to return the number of pins successfully configured, ignoring
246requests for other carriers. However, if no pin is configured (because
247no structure at all refers to the current carrier_name), the operation
248returns an error so the caller will know that it is running under a
249yet-unsupported carrier.
250
251So, for example, a driver that has been developed and tested on both
252the SPEC and the SVEC may request configuration of two different GPIO
253pins, and expect one such configuration to succeed - if none succeeds
254it most likely means that the current carrier is a still-unknown one.
255
256If, however, your GPIO pin has a specific known role, you can pass a
257special number in the gpio field, using one of the following macros:
258
259 #define FMC_GPIO_RAW(x) (x) /* 4096 of them */
260 #define FMC_GPIO_IRQ(x) ((x) + 0x1000) /* 256 of them */
261 #define FMC_GPIO_LED(x) ((x) + 0x1100) /* 256 of them */
262 #define FMC_GPIO_KEY(x) ((x) + 0x1200) /* 256 of them */
263 #define FMC_GPIO_TP(x) ((x) + 0x1300) /* 256 of them */
264 #define FMC_GPIO_USER(x) ((x) + 0x1400) /* 256 of them */
265
266Use of virtual GPIO numbers (anything but FMC_GPIO_RAW) is allowed
267provided the carrier_name field in the data structure is left
268unspecified (NULL). Each carrier is responsible for providing a mapping
269between virtual and physical GPIO numbers. The carrier may then use the
270_gpio field to cache the result of this mapping.
271
272All carriers must map their I/O lines to the sets above starting from
273zero. The SPEC, for example, maps interrupt pins 0 and 1, and test
274points 0 through 3 (even if the test points on the PCB are called
2755,6,7,8).
276
277If, for example, a driver requires a free LED and a test point (for a
278scope probe to be plugged at some point during development) it may ask
279for FMC_GPIO_LED(0) and FMC_GPIO_TP(0). Each carrier will provide
280suitable GPIO pins. Clearly, the person running the drivers will know
281the order used by the specific carrier driver in assigning leds and
282testpoints, so to make a carrier-dependent use of the diagnostic tools.
283
284In theory, some form of autodetection should be possible: a driver like
285the wr-nic (which uses IRQ(1) on the SPEC card) should configure
286IRQ(0), make a test with software-generated interrupts and configure
287IRQ(1) if the test fails. This probing step should be used because even
288if the wr-nic gateware is known to use IRQ1 on the SPEC, the driver
289should be carrier-independent and thus use IRQ(0) as a first bet -
290actually, the knowledge that IRQ0 may fail is carrier-dependent
291information, but using it doesn't make the driver unsuitable for other
292carriers.
293
294The return value of gpio_config is defined as follows:
295
296 * If no pin in the array can be used by the carrier, `-ENODEV'.
297
298 * If at least one virtual GPIO number cannot be mapped, `-ENOENT'.
299
300 * On success, 0 or positive. The value returned is the number of
301 high input bits (if no input is configured, the value for success
302 is 0).
303
304While I admit the procedure is not completely straightforward, it
305allows configuration, input and output with a single carrier operation.
306Given the typical use case of FMC devices, GPIO operations are not
307expected to ever by in hot paths, and GPIO access so fare has only been
308used to configure the interrupt pin, mode and polarity. Especially
309reading inputs is not expected to be common. If your device has GPIO
310capabilities in the hot path, you should consider using the kernel's
311GPIO mechanisms.
diff --git a/Documentation/fmc/fmc-chardev.txt b/Documentation/fmc/fmc-chardev.txt
new file mode 100644
index 000000000000..d9ccb278e597
--- /dev/null
+++ b/Documentation/fmc/fmc-chardev.txt
@@ -0,0 +1,64 @@
1fmc-chardev
2===========
3
4This is a simple generic driver, that allows user access by means of a
5character device (actually, one for each mezzanine it takes hold of).
6
7The char device is created as a misc device. Its name in /dev (as
8created by udev) is the same name as the underlying FMC device. Thus,
9the name can be a silly fmc-0000 look-alike if the device has no
10identifiers nor bus_id, a more specific fmc-0400 if the device has a
11bus-specific address but no associated name, or something like
12fdelay-0400 if the FMC core can rely on both a mezzanine name and a bus
13address.
14
15Currently the driver only supports read and write: you can lseek to the
16desired address and read or write a register.
17
18The driver assumes all registers are 32-bit in size, and only accepts a
19single read or write per system call. However, as a result of Unix read
20and write semantics, users can simply fread or fwrite bigger areas in
21order to dump or store bigger memory areas.
22
23There is currently no support for mmap, user-space interrupt management
24and DMA buffers. They may be added in later versions, if the need
25arises.
26
27The example below shows raw access to a SPEC card programmed with its
28golden FPGA file, that features an SDB structure at offset 256 - i.e.
2964 words. The mezzanine's EEPROM in this case is not programmed, so the
30default name is fmc-<bus><devfn>, and there are two cards in the system:
31
32 spusa.root# insmod fmc-chardev.ko
33 [ 1073.339332] spec 0000:02:00.0: Driver has no ID: matches all
34 [ 1073.345051] spec 0000:02:00.0: Created misc device "fmc-0200"
35 [ 1073.350821] spec 0000:04:00.0: Driver has no ID: matches all
36 [ 1073.356525] spec 0000:04:00.0: Created misc device "fmc-0400"
37 spusa.root# ls -l /dev/fmc*
38 crw------- 1 root root 10, 58 Nov 20 19:23 /dev/fmc-0200
39 crw------- 1 root root 10, 57 Nov 20 19:23 /dev/fmc-0400
40 spusa.root# dd bs=4 skip=64 count=1 if=/dev/fmc-0200 2> /dev/null | od -t x1z
41 0000000 2d 42 44 53 >-BDS<
42 0000004
43
44The simple program tools/fmc-mem in this package can access an FMC char
45device and read or write a word or a whole area. Actually, the program
46is not specific to FMC at all, it just uses lseek, read and write.
47
48Its first argument is the device name, the second the offset, the third
49(if any) the value to write and the optional last argument that must
50begin with "+" is the number of bytes to read or write. In case of
51repeated reading data is written to stdout; repeated writes read from
52stdin and the value argument is ignored.
53
54The following examples show reading the SDB magic number and the first
55SDB record from a SPEC device programmed with its golden image:
56
57 spusa.root# ./fmc-mem /dev/fmc-0200 100
58 5344422d
59 spusa.root# ./fmc-mem /dev/fmc-0200 100 +40 | od -Ax -t x1z
60 000000 2d 42 44 53 00 01 02 00 00 00 00 00 00 00 00 00 >-BDS............<
61 000010 00 00 00 00 ff 01 00 00 00 00 00 00 51 06 00 00 >............Q...<
62 000020 c9 42 a5 e6 02 00 00 00 11 05 12 20 2d 34 42 57 >.B......... -4BW<
63 000030 73 6f 72 43 72 61 62 73 49 53 47 2d 00 20 20 20 >sorCrabsISG-. <
64 000040
diff --git a/Documentation/fmc/fmc-fakedev.txt b/Documentation/fmc/fmc-fakedev.txt
new file mode 100644
index 000000000000..e85b74a4ae30
--- /dev/null
+++ b/Documentation/fmc/fmc-fakedev.txt
@@ -0,0 +1,36 @@
1fmc-fakedev
2===========
3
4This package includes a software-only device, called fmc-fakedev, which
5is able to register up to 4 mezzanines (by default it registers one).
6Unlike the SPEC driver, which creates an FMC device for each PCI cards
7it manages, this module creates a single instance of its set of
8mezzanines.
9
10It is meant as the simplest possible example of how a driver should be
11written, and it includes a fake EEPROM image (built using the tools
12described in *note FMC Identification::),, which by default is
13replicated for each fake mezzanine.
14
15You can also use this device to verify the match algorithms, by asking
16it to test your own EEPROM image. You can provide the image by means of
17the eeprom= module parameter: the new EEPROM image is loaded, as usual,
18by means of the firmware loader. This example shows the defaults and a
19custom EEPROM image:
20
21 spusa.root# insmod fmc-fakedev.ko
22 [ 99.971247] fake-fmc-carrier: mezzanine 0
23 [ 99.975393] Manufacturer: fake-vendor
24 [ 99.979624] Product name: fake-design-for-testing
25 spusa.root# rmmod fmc-fakedev
26 spusa.root# insmod fmc-fakedev.ko eeprom=fdelay-eeprom.bin
27 [ 121.447464] fake-fmc-carrier: Mezzanine 0: eeprom "fdelay-eeprom.bin"
28 [ 121.462725] fake-fmc-carrier: mezzanine 0
29 [ 121.466858] Manufacturer: CERN
30 [ 121.470477] Product name: FmcDelay1ns4cha
31 spusa.root# rmmod fmc-fakedev
32
33After loading the device, you can use the write_ee method do modify its
34own internal fake EEPROM: whenever the image is overwritten starting at
35offset 0, the module will unregister and register again the FMC device.
36This is shown in fmc-write-eeprom.txt
diff --git a/Documentation/fmc/fmc-trivial.txt b/Documentation/fmc/fmc-trivial.txt
new file mode 100644
index 000000000000..d1910bc67159
--- /dev/null
+++ b/Documentation/fmc/fmc-trivial.txt
@@ -0,0 +1,17 @@
1fmc-trivial
2===========
3
4The simple module fmc-trivial is just a simple client that registers an
5interrupt handler. I used it to verify the basic mechanism of the FMC
6bus and how interrupts worked.
7
8The module implements the generic FMC parameters, so it can program a
9different gateware file in each card. The whole list of parameters it
10accepts are:
11
12`busid='
13`gateware='
14 Generic parameters. See mezzanine.txt
15
16
17This driver is worth reading, in my opinion.
diff --git a/Documentation/fmc/fmc-write-eeprom.txt b/Documentation/fmc/fmc-write-eeprom.txt
new file mode 100644
index 000000000000..44a3bc678bf0
--- /dev/null
+++ b/Documentation/fmc/fmc-write-eeprom.txt
@@ -0,0 +1,125 @@
1fmc-write-eeprom
2================
3
4This module is designed to load a binary file from /lib/firmware and to
5write it to the internal EEPROM of the mezzanine card. This driver uses
6the `busid' generic parameter.
7
8Overwriting the EEPROM is not something you should do daily, and it is
9expected to only happen during manufacturing. For this reason, the
10module makes it unlikely for the random user to change a working EEPROM.
11
12The module takes the following measures:
13
14 * It accepts a `file=' argument (within /lib/firmware) and if no
15 such argument is received, it doesn't write anything to EEPROM
16 (i.e. there is no default file name).
17
18 * If the file name ends with `.bin' it is written verbatim starting
19 at offset 0.
20
21 * If the file name ends with `.tlv' it is interpreted as
22 type-length-value (i.e., it allows writev(2)-like operation).
23
24 * If the file name doesn't match any of the patterns above, it is
25 ignored and no write is performed.
26
27 * Only cards listed with `busid=' are written to. If no busid is
28 specified, no programming is done (and the probe function of the
29 driver will fail).
30
31
32Each TLV tuple is formatted in this way: the header is 5 bytes,
33followed by data. The first byte is `w' for write, the next two bytes
34represent the address, in little-endian byte order, and the next two
35represent the data length, in little-endian order. The length does not
36include the header (it is the actual number of bytes to be written).
37
38This is a real example: that writes 5 bytes at position 0x110:
39
40 spusa.root# od -t x1 -Ax /lib/firmware/try.tlv
41 000000 77 10 01 05 00 30 31 32 33 34
42 00000a
43 spusa.root# insmod /tmp/fmc-write-eeprom.ko busid=0x0200 file=try.tlv
44 [19983.391498] spec 0000:03:00.0: write 5 bytes at 0x0110
45 [19983.414615] spec 0000:03:00.0: write_eeprom: success
46
47Please note that you'll most likely want to use SDBFS to build your
48EEPROM image, at least if your mezzanines are being used in the White
49Rabbit environment. For this reason the TLV format is not expected to
50be used much and is not expected to be developed further.
51
52If you want to try reflashing fake EEPROM devices, you can use the
53fmc-fakedev.ko module (see *note fmc-fakedev::). Whenever you change
54the image starting at offset 0, it will deregister and register again
55after two seconds. Please note, however, that if fmc-write-eeprom is
56still loaded, the system will associate it to the new device, which
57will be reprogrammed and thus will be unloaded after two seconds. The
58following example removes the module after it reflashed fakedev the
59first time.
60
61 spusa.root# insmod fmc-fakedev.ko
62 [ 72.984733] fake-fmc: Manufacturer: fake-vendor
63 [ 72.989434] fake-fmc: Product name: fake-design-for-testing
64 spusa.root# insmod fmc-write-eeprom.ko busid=0 file=fdelay-eeprom.bin; \
65 rmmod fmc-write-eeprom
66 [ 130.874098] fake-fmc: Matching a generic driver (no ID)
67 [ 130.887845] fake-fmc: programming 6155 bytes
68 [ 130.894567] fake-fmc: write_eeprom: success
69 [ 132.895794] fake-fmc: Manufacturer: CERN
70 [ 132.899872] fake-fmc: Product name: FmcDelay1ns4cha
71
72
73Writing to the EEPROM
74=====================
75
76Once you have created a binary file for your EEPROM, you can write it
77to the storage medium using the fmc-write-eeprom (See *note
78fmc-write-eeprom::, while relying on a carrier driver. The procedure
79here shown here uses the SPEC driver
80(`http://www.ohwr.org/projects/spec-sw').
81
82The example assumes no driver is already loaded (actually, I unloaded
83them by hand as everything loads automatically at boot time after you
84installed the modules), and shows kernel messages together with
85commands. Here the prompt is spusa.root# and two SPEC cards are plugged
86in the system.
87
88 spusa.root# insmod fmc.ko
89 spusa.root# insmod spec.ko
90 [13972.382818] spec 0000:02:00.0: probe for device 0002:0000
91 [13972.392773] spec 0000:02:00.0: got file "fmc/spec-init.bin", 1484404 (0x16a674) bytes
92 [13972.591388] spec 0000:02:00.0: FPGA programming successful
93 [13972.883011] spec 0000:02:00.0: EEPROM has no FRU information
94 [13972.888719] spec 0000:02:00.0: No device_id filled, using index
95 [13972.894676] spec 0000:02:00.0: No mezzanine_name found
96 [13972.899863] /home/rubini/wip/spec-sw/kernel/spec-gpio.c - spec_gpio_init
97 [13972.906578] spec 0000:04:00.0: probe for device 0004:0000
98 [13972.916509] spec 0000:04:00.0: got file "fmc/spec-init.bin", 1484404 (0x16a674) bytes
99 [13973.115096] spec 0000:04:00.0: FPGA programming successful
100 [13973.401798] spec 0000:04:00.0: EEPROM has no FRU information
101 [13973.407474] spec 0000:04:00.0: No device_id filled, using index
102 [13973.413417] spec 0000:04:00.0: No mezzanine_name found
103 [13973.418600] /home/rubini/wip/spec-sw/kernel/spec-gpio.c - spec_gpio_init
104 spusa.root# ls /sys/bus/fmc/devices
105 fmc-0000 fmc-0001
106 spusa.root# insmod fmc-write-eeprom.ko busid=0x0200 file=fdelay-eeprom.bin
107 [14103.966259] spec 0000:02:00.0: Matching an generic driver (no ID)
108 [14103.975519] spec 0000:02:00.0: programming 6155 bytes
109 [14126.373762] spec 0000:02:00.0: write_eeprom: success
110 [14126.378770] spec 0000:04:00.0: Matching an generic driver (no ID)
111 [14126.384903] spec 0000:04:00.0: fmc_write_eeprom: no filename given: not programming
112 [14126.392600] fmc_write_eeprom: probe of fmc-0001 failed with error -2
113
114Reading back the EEPROM
115=======================
116
117In order to read back the binary content of the EEPROM of your
118mezzanine device, the bus creates a read-only sysfs file called eeprom
119for each mezzanine it knows about:
120
121 spusa.root# cd /sys/bus/fmc/devices; ls -l */eeprom
122 -r--r--r-- 1 root root 8192 Apr 9 16:53 FmcDelay1ns4cha-f001/eeprom
123 -r--r--r-- 1 root root 8192 Apr 9 17:19 fake-design-for-testing-f002/eeprom
124 -r--r--r-- 1 root root 8192 Apr 9 17:19 fake-design-for-testing-f003/eeprom
125 -r--r--r-- 1 root root 8192 Apr 9 17:19 fmc-f004/eeprom
diff --git a/Documentation/fmc/identifiers.txt b/Documentation/fmc/identifiers.txt
new file mode 100644
index 000000000000..3bb577ff0d52
--- /dev/null
+++ b/Documentation/fmc/identifiers.txt
@@ -0,0 +1,168 @@
1FMC Identification
2******************
3
4The FMC standard requires every compliant mezzanine to carry
5identification information in an I2C EEPROM. The information must be
6laid out according to the "IPMI Platform Management FRU Information",
7where IPMI is a lie I'd better not expand, and FRU means "Field
8Replaceable Unit".
9
10The FRU information is an intricate unreadable binary blob that must
11live at offset 0 of the EEPROM, and typically extends for a few hundred
12bytes. The standard allows the application to use all the remaining
13storage area of the EEPROM as it wants.
14
15This chapter explains how to create your own EEPROM image and how to
16write it in your mezzanine, as well as how devices and drivers are
17paired at run time. EEPROM programming uses tools that are part of this
18package and SDB (part of the fpga-config-space package).
19
20The first sections are only interesting for manufacturers who need to
21write the EEPROM. If you are just a software developer writing an FMC
22device or driver, you may jump straight to *note SDB Support::.
23
24
25Building the FRU Structure
26==========================
27
28If you want to know the internals of the FRU structure and despair, you
29can retrieve the document from
30`http://download.intel.com/design/servers/ipmi/FRU1011.pdf' . The
31standard is awful and difficult without reason, so we only support the
32minimum mandatory subset - we create a simple structure and parse it
33back at run time, but we are not able to either generate or parse more
34arcane features like non-english languages and 6-bit text. If you need
35more items of the FRU standard for your boards, please submit patches.
36
37This package includes the Python script that Matthieu Cattin wrote to
38generate the FRU binary blob, based on an helper libipmi by Manohar
39Vanga and Matthieu himself. I changed the test script to receive
40parameters from the command line or from the environment (the command
41line takes precedence)
42
43To make a long story short, in order to build a standard-compliant
44binary file to be burned in your EEPROM, you need the following items:
45
46 Environment Opt Official Name Default
47---------------------------------------------------------------------
48 FRU_VENDOR -v "Board Manufacturer" fmc-example
49 FRU_NAME -n "Board Product Name" mezzanine
50 FRU_SERIAL -s `Board Serial Number" 0001
51 FRU_PART -p "Board Part Number" sample-part
52 FRU_OUTPUT -o not applicable /dev/stdout
53
54The "Official Name" above is what you find in the FRU official
55documentation, chapter 11, page 7 ("Board Info Area Format"). The
56output option is used to save the generated binary to a specific file
57name instead of stdout.
58
59You can pass the items to the FRU generator either in the environment
60or on the command line. This package has currently no support for
61specifying power consumption or such stuff, but I plan to add it as
62soon as I find some time for that.
63
64FIXME: consumption etc for FRU are here or in PTS?
65
66The following example creates a binary image for a specific board:
67
68 ./tools/fru-generator -v CERN -n FmcAdc100m14b4cha \
69 -s HCCFFIA___-CR000003 -p EDA-02063-V5-0 > eeprom.bin
70
71The following example shows a script that builds several binary EEPROM
72images for a series of boards, changing the serial number for each of
73them. The script uses a mix of environment variables and command line
74options, and uses the same string patterns shown above.
75
76 #!/bin/sh
77
78 export FRU_VENDOR="CERN"
79 export FRU_NAME="FmcAdc100m14b4cha"
80 export FRU_PART="EDA-02063-V5-0"
81
82 serial="HCCFFIA___-CR"
83
84 for number in $(seq 1 50); do
85 # build number-string "ns"
86 ns="$(printf %06d $number)"
87 ./fru-generator -s "${serial}${ns}" > eeprom-${ns}.bin
88 done
89
90
91Using SDB-FS in the EEPROM
92==========================
93
94If you want to use SDB as a filesystem in the EEPROM device within the
95mezzanine, you should create one such filesystem using gensdbfs, from
96the fpga-config-space package on OHWR.
97
98By using an SBD filesystem you can cluster several files in a single
99EEPROM, so both the host system and a soft-core running in the FPGA (if
100any) can access extra production-time information.
101
102We chose to use SDB as a storage filesystem because the format is very
103simple, and both the host system and the soft-core will likely already
104include support code for such format. The SDB library offered by the
105fpga-config-space is less than 1kB under LM32, so it proves quite up to
106the task.
107
108The SDB entry point (which acts as a directory listing) cannot live at
109offset zero in the flash device, because the FRU information must live
110there. To avoid wasting precious storage space while still allowing
111for more-than-minimal FRU structures, the fmc.ko will look for the SDB
112record at address 256, 512 and 1024.
113
114In order to generate the complete EEPROM image you'll need a
115configuration file for gensdbfs: you tell the program where to place
116the sdb entry point, and you must force the FRU data file to be placed
117at the beginning of the storage device. If needed, you can also place
118other files at a special offset (we sometimes do it for backward
119compatibility with drivers we wrote before implementing SDB for flash
120memory).
121
122The directory tools/sdbfs of this package includes a well-commented
123example that you may want to use as a starting point (the comments are
124in the file called -SDB-CONFIG-). Reading documentation for gensdbfs
125is a suggested first step anyways.
126
127This package (generic FMC bus support) only accesses two files in the
128EEPROM: the FRU information, at offset zero, with a suggested filename
129of IPMI-FRU and the short name for the mezzanine, in a file called
130name. The IPMI-FRU name is not mandatory, but a strongly suggested
131choice; the name filename is mandatory, because this is the preferred
132short name used by the FMC core. For example, a name of "fdelay" may
133supplement a Product Name like "FmcDelay1ns4cha" - exactly as
134demonstrated in `tools/sdbfs'.
135
136Note: SDB access to flash memory is not yet supported, so the short
137name currently in use is just the "Product Name" FRU string.
138
139The example in tools/sdbfs includes an extra file, that is needed by
140the fine-delay driver, and must live at a known address of 0x1800. By
141running gensdbfs on that directory you can output your binary EEPROM
142image (here below spusa$ is the shell prompt):
143
144 spusa$ ../fru-generator -v CERN -n FmcDelay1ns4cha -s proto-0 \
145 -p EDA-02267-V3 > IPMI-FRU
146 spusa$ ls -l
147 total 16
148 -rw-rw-r-- 1 rubini staff 975 Nov 19 18:08 --SDB-CONFIG--
149 -rw-rw-r-- 1 rubini staff 216 Nov 19 18:13 IPMI-FRU
150 -rw-rw-r-- 1 rubini staff 11 Nov 19 18:04 fd-calib
151 -rw-rw-r-- 1 rubini staff 7 Nov 19 18:04 name
152 spusa$ sudo gensdbfs . /lib/firmware/fdelay-eeprom.bin
153 spusa$ sdb-read -l -e 0x100 /lib/firmware/fdelay-eeprom.bin
154 /home/rubini/wip/sdbfs/userspace/sdb-read: listing format is to be defined
155 46696c6544617461:2e202020 00000100-000018ff .
156 46696c6544617461:6e616d65 00000200-00000206 name
157 46696c6544617461:66642d63 00001800-000018ff fd-calib
158 46696c6544617461:49504d49 00000000-000000d7 IPMI-FRU
159 spusa$ ../fru-dump /lib/firmware/fdelay-eeprom.bin
160 /lib/firmware/fdelay-eeprom.bin: manufacturer: CERN
161 /lib/firmware/fdelay-eeprom.bin: product-name: FmcDelay1ns4cha
162 /lib/firmware/fdelay-eeprom.bin: serial-number: proto-0
163 /lib/firmware/fdelay-eeprom.bin: part-number: EDA-02267-V3
164
165As expected, the output file is both a proper sdbfs object and an IPMI
166FRU information blob. The fd-calib file lives at offset 0x1800 and is
167over-allocated to 256 bytes, according to the configuration file for
168gensdbfs.
diff --git a/Documentation/fmc/mezzanine.txt b/Documentation/fmc/mezzanine.txt
new file mode 100644
index 000000000000..87910dbfc91e
--- /dev/null
+++ b/Documentation/fmc/mezzanine.txt
@@ -0,0 +1,123 @@
1FMC Driver
2**********
3
4An FMC driver is concerned with the specific mezzanine and associated
5gateware. As such, it is expected to be independent of the carrier
6being used: it will perform I/O accesses only by means of
7carrier-provided functions.
8
9The matching between device and driver is based on the content of the
10EEPROM (as mandated by the FMC standard) or by the actual cores
11configured in the FPGA; the latter technique is used when the FPGA is
12already programmed when the device is registered to the bus core.
13
14In some special cases it is possible for a driver to directly access
15FPGA registers, by means of the `fpga_base' field of the device
16structure. This may be needed for high-bandwidth peripherals like fast
17ADC cards. If the device module registered a remote device (for example
18by means of Etherbone), the `fpga_base' pointer will be NULL.
19Therefore, drivers must be ready to deal with NULL base pointers, and
20fail gracefully. Most driver, however, are not expected to access the
21pointer directly but run fmc_readl and fmc_writel instead, which will
22work in any case.
23
24In even more special cases, the driver may access carrier-specific
25functionality: the `carrier_name' string allows the driver to check
26which is the current carrier and make use of the `carrier_data'
27pointer. We chose to use carrier names rather than numeric identifiers
28for greater flexibility, but also to avoid a central registry within
29the `fmc.h' file - we hope other users will exploit our framework with
30their own carriers. An example use of carrier names is in GPIO setup
31(see *note The GPIO Abstraction::), although the name match is not
32expected to be performed by the driver. If you depend on specific
33carriers, please check the carrier name and fail gracefully if your
34driver finds it is running in a yet-unknown-to-it environment.
35
36
37ID Table
38========
39
40Like most other Linux drivers, and FMC driver must list all the devices
41which it is able to drive. This is usually done by means of a device
42table, but in FMC we can match hardware based either on the contents of
43their EEPROM or on the actual FPGA cores that can be enumerated.
44Therefore, we have two tables of identifiers.
45
46Matching of FRU information depends on two names, the manufacturer (or
47vendor) and the device (see *note FMC Identification::); for
48flexibility during production (i.e. before writing to the EEPROM) the
49bus supports a catch-all driver that specifies NULL strings. For this
50reason, the table is specified as pointer-and-length, not a a
51null-terminated array - the entry with NULL names can be a valid entry.
52
53Matching on FPGA cores depends on two numeric fields: the 64-bit vendor
54number and the 32-bit device number. Support for matching based on
55class is not yet implemented. Each device is expected to be uniquely
56identified by an array of cores (it matches if all of the cores are
57instantiated), and for consistency the list is passed as
58pointer-and-length. Several similar devices can be driven by the same
59driver, and thus the driver specifies and array of such arrays.
60
61The complete set of involved data structures is thus the following:
62
63 struct fmc_fru_id { char *manufacturer; char *product_name; };
64 struct fmc_sdb_one_id { uint64_t vendor; uint32_t device; };
65 struct fmc_sdb_id { struct fmc_sdb_one_id *cores; int cores_nr; };
66
67 struct fmc_device_id {
68 struct fmc_fru_id *fru_id; int fru_id_nr;
69 struct fmc_sdb_id *sdb_id; int sdb_id_nr;
70 };
71
72A better reference, with full explanation, is the <linux/fmc.h> header.
73
74
75Module Parameters
76=================
77
78Most of the FMC drivers need the same set of kernel parameters. This
79package includes support to implement common parameters by means of
80fields in the `fmc_driver' structure and simple macro definitions.
81
82The parameters are carrier-specific, in that they rely on the busid
83concept, that varies among carriers. For the SPEC, the identifier is a
84PCI bus and devfn number, 16 bits wide in total; drivers for other
85carriers will most likely offer something similar but not identical,
86and some code duplication is unavoidable.
87
88This is the list of parameters that are common to several modules to
89see how they are actually used, please look at spec-trivial.c.
90
91`busid='
92 This is an array of integers, listing carrier-specific
93 identification numbers. For PIC, for example, `0x0400' represents
94 bus 4, slot 0. If any such ID is specified, the driver will only
95 accept to drive cards that appear in the list (even if the FMC ID
96 matches). This is accomplished by the validate carrier method.
97
98`gateware='
99 The argument is an array of strings. If no busid= is specified,
100 the first string of gateware= is used for all cards; otherwise the
101 identifiers and gateware names are paired one by one, in the order
102 specified.
103
104`show_sdb='
105 For modules supporting it, this parameter asks to show the SDB
106 internal structure by means of kernel messages. It is disabled by
107 default because those lines tend to hide more important messages,
108 if you look at the system console while loading the drivers.
109 Note: the parameter is being obsoleted, because fmc.ko itself now
110 supports dump_sdb= that applies to every client driver.
111
112
113For example, if you are using the trivial driver to load two different
114gateware files to two different cards, you can use the following
115parameters to load different binaries to the cards, after looking up
116the PCI identifiers. This has been tested with a SPEC carrier.
117
118 insmod fmc-trivial.ko \
119 busid=0x0200,0x0400 \
120 gateware=fmc/fine-delay.bin,fmc/simple-dio.bin
121
122Please note that not all sub-modules support all of those parameters.
123You can use modinfo to check what is supported by each module.
diff --git a/Documentation/fmc/parameters.txt b/Documentation/fmc/parameters.txt
new file mode 100644
index 000000000000..59edf088e3a4
--- /dev/null
+++ b/Documentation/fmc/parameters.txt
@@ -0,0 +1,56 @@
1Module Parameters in fmc.ko
2***************************
3
4The core driver receives two module parameters, meant to help debugging
5client modules. Both parameters can be modified by writing to
6/sys/module/fmc/parameters/, because they are used when client drivers
7are devices are registered, not when fmc.ko is loaded.
8
9`dump_eeprom='
10 If not zero, the parameter asks the bus controller to dump the
11 EEPROM of any device that is registered, using printk.
12
13`dump_sdb='
14 If not zero, the parameter prints the SDB tree of every FPGA it is
15 loaded by fmc_reprogram(). If greater than one, it asks to dump
16 the binary content of SDB records. This currently only dumps the
17 top-level SDB array, though.
18
19
20EEPROM dumping avoids repeating lines, since most of the contents is
21usually empty and all bits are one or zero. This is an example of the
22output:
23
24 [ 6625.850480] spec 0000:02:00.0: FPGA programming successful
25 [ 6626.139949] spec 0000:02:00.0: Manufacturer: CERN
26 [ 6626.144666] spec 0000:02:00.0: Product name: FmcDelay1ns4cha
27 [ 6626.150370] FMC: mezzanine 0: 0000:02:00.0 on SPEC
28 [ 6626.155179] FMC: dumping eeprom 0x2000 (8192) bytes
29 [ 6626.160087] 0000: 01 00 00 01 00 0b 00 f3 01 0a 00 a5 85 87 c4 43
30 [ 6626.167069] 0010: 45 52 4e cf 46 6d 63 44 65 6c 61 79 31 6e 73 34
31 [ 6626.174019] 0020: 63 68 61 c7 70 72 6f 74 6f 2d 30 cc 45 44 41 2d
32 [ 6626.180975] 0030: 30 32 32 36 37 2d 56 33 da 32 30 31 32 2d 31 31
33 [...]
34 [ 6626.371366] 0200: 66 64 65 6c 61 79 0a 00 00 00 00 00 00 00 00 00
35 [ 6626.378359] 0210: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
36 [ 6626.385361] [...]
37 [ 6626.387308] 1800: 70 6c 61 63 65 68 6f 6c 64 65 72 ff ff ff ff ff
38 [ 6626.394259] 1810: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff
39 [ 6626.401250] [...]
40
41The dump of SDB looks like the following; the example shows the simple
42golden gateware for the SPEC card, removing the leading timestamps to
43fit the page:
44
45 spec 0000:02:00.0: SDB: 00000651:e6a542c9 WB4-Crossbar-GSI
46 spec 0000:02:00.0: SDB: 0000ce42:ff07fc47 WR-Periph-Syscon (00000000-000000ff)
47 FMC: mezzanine 0: 0000:02:00.0 on SPEC
48 FMC: poor dump of sdb first level:
49 0000: 53 44 42 2d 00 02 01 00 00 00 00 00 00 00 00 00
50 0010: 00 00 00 00 00 00 01 ff 00 00 00 00 00 00 06 51
51 0020: e6 a5 42 c9 00 00 00 02 20 12 05 11 57 42 34 2d
52 0030: 43 72 6f 73 73 62 61 72 2d 47 53 49 20 20 20 00
53 0040: 00 00 01 01 00 00 00 07 00 00 00 00 00 00 00 00
54 0050: 00 00 00 00 00 00 00 ff 00 00 00 00 00 00 ce 42
55 0060: ff 07 fc 47 00 00 00 01 20 12 03 05 57 52 2d 50
56 0070: 65 72 69 70 68 2d 53 79 73 63 6f 6e 20 20 20 01
diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1.generic
index 212f4ac31c01..a31c5a242973 100644
--- a/Documentation/w1/w1.generic
+++ b/Documentation/w1/w1.generic
@@ -25,8 +25,8 @@ When a w1 master driver registers with the w1 subsystem, the following occurs:
25 - sysfs entries for that w1 master are created 25 - sysfs entries for that w1 master are created
26 - the w1 bus is periodically searched for new slave devices 26 - the w1 bus is periodically searched for new slave devices
27 27
28When a device is found on the bus, w1 core checks if driver for its family is 28When a device is found on the bus, w1 core tries to load the driver for its family
29loaded. If so, the family driver is attached to the slave. 29and check if it is loaded. If so, the family driver is attached to the slave.
30If there is no driver for the family, default one is assigned, which allows to perform 30If there is no driver for the family, default one is assigned, which allows to perform
31almost any kind of operations. Each logical operation is a transaction 31almost any kind of operations. Each logical operation is a transaction
32in nature, which can contain several (two or one) low-level operations. 32in nature, which can contain several (two or one) low-level operations.
generated by cgit v1.2.2 (git 2.25.0) at 2025-01-06 18:29:02 -0500