blob: 30ded732027e2814ccc8c4cf5690a84fbc8ebc30
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 an 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 the 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 into 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 a so |
54 | called Chameleon FPGA device found on some hardware produced my MEN Mikro |
55 | Elektronik GmbH. These devices are multi-function devices implemented in a |
56 | single FPGA and usually attached via some sort of PCI or PCIe link. Each |
57 | FPGA contains a header section describing the content of the FPGA. The |
58 | header lists the device id, PCI BAR, offset from the beginning of the PCI |
59 | BAR, size in the FPGA, interrupt number and some other properties currently |
60 | not handled by the MCB implementation. |
61 | |
62 | 2.2 Carrier Devices |
63 | -------------------- |
64 | A carrier device is just an abstraction for the real world physical bus the |
65 | Chameleon FPGA is attached to. Some IP Core drivers may need to interact with |
66 | properties of the carrier device (like querying the IRQ number of a PCI |
67 | device). To provide abstraction from the real hardware bus, an MCB carrier |
68 | device provides callback methods to translate the driver's MCB function calls |
69 | to hardware related function calls. For example a carrier device may |
70 | implement the get_irq() method which can be translated into a hardware bus |
71 | query for the IRQ number the device should use. |
72 | |
73 | 2.3 Parser |
74 | ----------- |
75 | The parser reads the first 512 bytes of a Chameleon device and parses the |
76 | Chameleon table. Currently the parser only supports the Chameleon v2 variant |
77 | of the Chameleon table but can easily be adopted to support an older or |
78 | possible future variant. While parsing the table's entries new MCB devices |
79 | are allocated and their resources are assigned according to the resource |
80 | assignment in the Chameleon table. After resource assignment is finished, the |
81 | MCB devices are registered at the MCB and thus at the driver core of the |
82 | Linux kernel. |
83 | |
84 | 3 Resource handling |
85 | ==================== |
86 | The current implementation assigns exactly one memory and one IRQ resource |
87 | per MCB device. But this is likely going to change in the future. |
88 | |
89 | 3.1 Memory Resources |
90 | --------------------- |
91 | Each MCB device has exactly one memory resource, which can be requested from |
92 | the MCB bus. This memory resource is the physical address of the MCB device |
93 | inside the carrier and is intended to be passed to ioremap() and friends. It |
94 | is already requested from the kernel by calling request_mem_region(). |
95 | |
96 | 3.2 IRQs |
97 | --------- |
98 | Each MCB device has exactly one IRQ resource, which can be requested from the |
99 | MCB bus. If a carrier device driver implements the ->get_irq() callback |
100 | method, the IRQ number assigned by the carrier device will be returned, |
101 | otherwise the IRQ number inside the Chameleon table will be returned. This |
102 | number is suitable to be passed to request_irq(). |
103 | |
104 | 4 Writing an MCB driver |
105 | ======================= |
106 | |
107 | 4.1 The driver structure |
108 | ------------------------- |
109 | Each MCB driver has a structure to identify the device driver as well as |
110 | device ids which identify the IP Core inside the FPGA. The driver structure |
111 | also contains callback methods which get executed on driver probe and |
112 | removal from the system. |
113 | |
114 | |
115 | static const struct mcb_device_id foo_ids[] = { |
116 | { .device = 0x123 }, |
117 | { } |
118 | }; |
119 | MODULE_DEVICE_TABLE(mcb, foo_ids); |
120 | |
121 | static struct mcb_driver foo_driver = { |
122 | driver = { |
123 | .name = "foo-bar", |
124 | .owner = THIS_MODULE, |
125 | }, |
126 | .probe = foo_probe, |
127 | .remove = foo_remove, |
128 | .id_table = foo_ids, |
129 | }; |
130 | |
131 | 4.2 Probing and attaching |
132 | -------------------------- |
133 | When a driver is loaded and the MCB devices it services are found, the MCB |
134 | core will call the driver's probe callback method. When the driver is removed |
135 | from the system, the MCB core will call the driver's remove callback method. |
136 | |
137 | |
138 | static init foo_probe(struct mcb_device *mdev, const struct mcb_device_id *id); |
139 | static void foo_remove(struct mcb_device *mdev); |
140 | |
141 | 4.3 Initializing the driver |
142 | ---------------------------- |
143 | When the kernel is booted or your foo driver module is inserted, you have to |
144 | perform driver initialization. Usually it is enough to register your driver |
145 | module at the MCB core. |
146 | |
147 | |
148 | static int __init foo_init(void) |
149 | { |
150 | return mcb_register_driver(&foo_driver); |
151 | } |
152 | module_init(foo_init); |
153 | |
154 | static void __exit foo_exit(void) |
155 | { |
156 | mcb_unregister_driver(&foo_driver); |
157 | } |
158 | module_exit(foo_exit); |
159 | |
160 | The module_mcb_driver() macro can be used to reduce the above code. |
161 | |
162 | |
163 | module_mcb_driver(foo_driver); |
164 |