1 =================
2 MEN Chameleon Bus
3 =================
4
5 .. Table of Contents
6 =================
7 1 Introduction
8 1.1 Scope of this Document
9 1.2 Limitations of the current implemen
10 2 Architecture
11 2.1 MEN Chameleon Bus
12 2.2 Carrier Devices
13 2.3 Parser
14 3 Resource handling
15 3.1 Memory Resources
16 3.2 IRQs
17 4 Writing an MCB driver
18 4.1 The driver structure
19 4.2 Probing and attaching
20 4.3 Initializing the driver
21 4.4 Using DMA
22
23
24 Introduction
25 ============
26
27 This document describes the architecture and i
28 Chameleon Bus (called MCB throughout this docu
29
30 Scope of this Document
31 ----------------------
32
33 This document is intended to be a short overvi
34 implementation and does by no means describe t
35 based devices.
36
37 Limitations of the current implementation
38 -----------------------------------------
39
40 The current implementation is limited to PCI a
41 that only use a single memory resource and sha
42 implemented are:
43
44 - Multi-resource MCB devices like the VME Cont
45 - MCB devices that need another MCB device, li
46 buffer descriptors or a video controller's v
47 - A per-carrier IRQ domain for carrier devices
48 per MCB device like PCIe based carriers with
49
50 Architecture
51 ============
52
53 MCB is divided into 3 functional blocks:
54
55 - The MEN Chameleon Bus itself,
56 - drivers for MCB Carrier Devices and
57 - the parser for the Chameleon table.
58
59 MEN Chameleon Bus
60 -----------------
61
62 The MEN Chameleon Bus is an artificial bus sys
63 called Chameleon FPGA device found on some har
64 Elektronik GmbH. These devices are multi-funct
65 single FPGA and usually attached via some sort
66 FPGA contains a header section describing the
67 header lists the device id, PCI BAR, offset fr
68 BAR, size in the FPGA, interrupt number and so
69 not handled by the MCB implementation.
70
71 Carrier Devices
72 ---------------
73
74 A carrier device is just an abstraction for th
75 Chameleon FPGA is attached to. Some IP Core dr
76 properties of the carrier device (like queryin
77 device). To provide abstraction from the real
78 device provides callback methods to translate
79 to hardware related function calls. For exampl
80 implement the get_irq() method which can be tr
81 query for the IRQ number the device should use
82
83 Parser
84 ------
85
86 The parser reads the first 512 bytes of a Cham
87 Chameleon table. Currently the parser only sup
88 of the Chameleon table but can easily be adopt
89 possible future variant. While parsing the tab
90 are allocated and their resources are assigned
91 assignment in the Chameleon table. After resou
92 MCB devices are registered at the MCB and thus
93 Linux kernel.
94
95 Resource handling
96 =================
97
98 The current implementation assigns exactly one
99 per MCB device. But this is likely going to ch
100
101 Memory Resources
102 ----------------
103
104 Each MCB device has exactly one memory resourc
105 the MCB bus. This memory resource is the physi
106 inside the carrier and is intended to be passe
107 is already requested from the kernel by callin
108
109 IRQs
110 ----
111
112 Each MCB device has exactly one IRQ resource,
113 MCB bus. If a carrier device driver implements
114 method, the IRQ number assigned by the carrier
115 otherwise the IRQ number inside the Chameleon
116 number is suitable to be passed to request_irq
117
118 Writing an MCB driver
119 =====================
120
121 The driver structure
122 --------------------
123
124 Each MCB driver has a structure to identify th
125 device ids which identify the IP Core inside t
126 also contains callback methods which get execu
127 removal from the system::
128
129 static const struct mcb_device_id foo_
130 { .device = 0x123 },
131 { }
132 };
133 MODULE_DEVICE_TABLE(mcb, foo_ids);
134
135 static struct mcb_driver foo_driver =
136 driver = {
137 .name = "foo-bar",
138 .owner = THIS_MODULE,
139 },
140 .probe = foo_probe,
141 .remove = foo_remove,
142 .id_table = foo_ids,
143 };
144
145 Probing and attaching
146 ---------------------
147
148 When a driver is loaded and the MCB devices it
149 core will call the driver's probe callback met
150 from the system, the MCB core will call the dr
151
152 static init foo_probe(struct mcb_devic
153 static void foo_remove(struct mcb_devi
154
155 Initializing the driver
156 -----------------------
157
158 When the kernel is booted or your foo driver m
159 perform driver initialization. Usually it is e
160 module at the MCB core::
161
162 static int __init foo_init(void)
163 {
164 return mcb_register_driver(&fo
165 }
166 module_init(foo_init);
167
168 static void __exit foo_exit(void)
169 {
170 mcb_unregister_driver(&foo_dri
171 }
172 module_exit(foo_exit);
173
174 The module_mcb_driver() macro can be used to r
175
176 module_mcb_driver(foo_driver);
177
178 Using DMA
179 ---------
180
181 To make use of the kernel's DMA-API's function
182 carrier device's 'struct device'. Fortunately
183 pointer (->dma_dev) to the carrier's device fo
184
185 ret = dma_set_mask_and_coherent(&mdev-
186 if (rc)
187 /* Handle errors */
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.