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