Commit | Line | Data |
---|---|---|
b9f2f459 JT |
1 | MEN Chameleon Bus |
2 | ================= | |
3 | ||
4 | Table of Contents | |
5 | ================= | |
6 | 1 Introduction | |
7 | 1.1 Scope of this Document | |
8 | 1.2 Limitations of the current implementation | |
9 | 2 Architecture | |
10 | 2.1 MEN Chameleon Bus | |
11 | 2.2 Carrier Devices | |
12 | 2.3 Parser | |
13 | 3 Resource handling | |
14 | 3.1 Memory Resources | |
15 | 3.2 IRQs | |
16 | 4 Writing a MCB driver | |
17 | 4.1 The driver structure | |
18 | 4.2 Probing and attaching | |
19 | 4.3 Initializing the driver | |
20 | ||
21 | ||
22 | 1 Introduction | |
23 | =============== | |
24 | This document describes the architecture and implementation of the MEN | |
25 | Chameleon Bus (called MCB throughout this document). | |
26 | ||
27 | 1.1 Scope of this Document | |
28 | --------------------------- | |
29 | This document is intended to be a short overview of the current | |
30 | implementation and does by no means describe to complete possibilities of MCB | |
31 | based devices. | |
32 | ||
33 | 1.2 Limitations of the current implementation | |
34 | ---------------------------------------------- | |
35 | The current implementation is limited to PCI and PCIe based carrier devices | |
36 | that only use a single memory resource and share the PCI legacy IRQ. Not | |
37 | implemented are: | |
38 | - Multi-resource MCB devices like the VME Controller or M-Module carrier. | |
39 | - MCB devices that need another MCB device, like SRAM for a DMA Controller's | |
40 | buffer descriptors or a video controller's video memory. | |
41 | - A per-carrier IRQ domain for carrier devices that have one (or more) IRQs | |
42 | per MCB device like PCIe based carriers with MSI or MSI-X support. | |
43 | ||
44 | 2 Architecture | |
45 | =============== | |
46 | MCB is divided in 3 functional blocks: | |
47 | - The MEN Chameleon Bus itself, | |
48 | - drivers for MCB Carrier Devices and | |
49 | - the parser for the Chameleon table. | |
50 | ||
51 | 2.1 MEN Chameleon Bus | |
52 | ---------------------- | |
53 | The MEN Chameleon Bus is an artificial bus system that attaches to an MEN | |
54 | Chameleon FPGA device. These devices are multi-function devices implemented | |
55 | in a single FPGA and usually attached via some sort of PCI or PCIe link. Each | |
56 | FPGA contains a header section describing the content of the FPGA. The header | |
57 | lists the device id, PCI BAR, offset from the beginning of the PCI BAR, size | |
58 | in the FPGA, interrupt number and some other properties currently not handled | |
59 | by the MCB implementation. | |
60 | ||
61 | 2.2 Carrier Devices | |
62 | -------------------- | |
63 | A carrier device is just an abstraction for the real world physical bus the | |
64 | chameleon FPGA is attached to. Some IP Core drivers may need to interact with | |
65 | properties of the carrier device (like querying the IRQ number of a PCI | |
66 | device). To provide abstraction from the real hardware bus, an MCB carrier | |
67 | device provides callback methods to translate the driver's MCB function calls | |
68 | to hardware related function calls. For example a carrier device may | |
69 | implement the get_irq() method which can be translate into a hardware bus | |
70 | query for the IRQ number the device should use. | |
71 | ||
72 | 2.3 Parser | |
73 | ----------- | |
74 | The parser reads the 1st 512 bytes of a chameleon device and parses the | |
75 | chameleon table. Currently the parser only supports the Chameleon v2 variant | |
76 | of the chameleon table but can easily be adopted to support an older or | |
77 | possible future variant. While parsing the table's entries new MCB devices | |
78 | are allocated and their resources are assigned according to the resource | |
79 | assignment in the chameleon table. After resource assignment is finished, the | |
80 | MCB devices are registered at the MCB and thus at the driver core of the | |
81 | Linux kernel. | |
82 | ||
83 | 3 Resource handling | |
84 | ==================== | |
85 | The current implementation assigns exactly one memory and one IRQ resource | |
86 | per MCB device. But this is likely going to change in the future. | |
87 | ||
88 | 3.1 Memory Resources | |
89 | --------------------- | |
90 | Each MCB device has exactly one memory resource, which can be requested from | |
91 | the MCB bus. This memory resource is the physical address of the MCB device | |
92 | inside the carrier and is intended to be passed to ioremap() and friends. It | |
93 | is already requested from the kernel by calling request_mem_region(). | |
94 | ||
95 | 3.2 IRQs | |
96 | --------- | |
97 | Each MCB device has exactly one IRQ resource, which can be requested from the | |
98 | MCB bus. If a carrier device driver implements the ->get_irq() callback | |
99 | method, the IRQ number assigned by the carrier device will be returned, | |
100 | otherwise the IRQ number inside the chameleon table will be returned. This | |
101 | number is suitable to be passed to request_irq(). | |
102 | ||
103 | 4 Writing a MCB driver | |
104 | ======================= | |
105 | ||
106 | 4.1 The driver structure | |
107 | ------------------------- | |
108 | Each MCB driver has a structure to identify the device driver as well as | |
109 | device ids which identify the IP Core inside the FPGA. The driver structure | |
110 | also contaings callback methods which get executed on driver probe and | |
111 | removal from the system. | |
112 | ||
113 | ||
114 | static const struct mcb_device_id foo_ids[] = { | |
115 | { .device = 0x123 }, | |
116 | { } | |
117 | }; | |
118 | MODULE_DEVICE_TABLE(mcb, foo_ids); | |
119 | ||
120 | static struct mcb_driver foo_driver = { | |
121 | driver = { | |
122 | .name = "foo-bar", | |
123 | .owner = THIS_MODULE, | |
124 | }, | |
125 | .probe = foo_probe, | |
126 | .remove = foo_remove, | |
127 | .id_table = foo_ids, | |
128 | }; | |
129 | ||
130 | 4.2 Probing and attaching | |
131 | -------------------------- | |
132 | When a driver is loaded and the MCB devices it services are found, the MCB | |
133 | core will call the driver's probe callback method. When the driver is removed | |
134 | from the system, the MCB core will call the driver's remove callback method. | |
135 | ||
136 | ||
137 | static init foo_probe(struct mcb_device *mdev, const struct mcb_device_id *id); | |
138 | static void foo_remove(struct mcb_device *mdev); | |
139 | ||
140 | 4.3 Initializing the driver | |
141 | ---------------------------- | |
142 | When the kernel is booted or your foo driver module is inserted, you have to | |
143 | perform driver initialization. Usually it is enough to register your driver | |
144 | module at the MCB core. | |
145 | ||
146 | ||
147 | static int __init foo_init(void) | |
148 | { | |
149 | return mcb_register_driver(&foo_driver); | |
150 | } | |
151 | module_init(foo_init); | |
152 | ||
153 | static void __exit foo_exit(void) | |
154 | { | |
155 | mcb_unregister_driver(&foo_driver); | |
156 | } | |
157 | module_exit(foo_exit); | |
158 | ||
159 | The module_mcb_driver() macro can be used to reduce the above code. | |
160 | ||
161 | ||
162 | module_mcb_driver(foo_driver); |