On 07/17/15 03:23, Johannes Thumshirn wrote:
> Add basic introductory documentation for the MEN Chameleon Bus.
>
> Signed-off-by: Johannes Thumshirn <jthumshirn@xxxxxxx>
> ---
>
> So this time I totally forgot about it..
>
> Changes from v1:
> - Renamed MCB.txt to men-chameleon-bus.txt
> - Added entry to MAINTAINERS file
>
> Documentation/men-chameleon-bus.txt | 162 ++++++++++++++++++++++++++++++++++++
> MAINTAINERS | 1 +
> 2 files changed, 163 insertions(+)
> create mode 100644 Documentation/men-chameleon-bus.txt
>
> diff --git a/Documentation/men-chameleon-bus.txt b/Documentation/men-chameleon-bus.txt
> new file mode 100644
> index 0000000..6d7bdb5
> --- /dev/null
> +++ b/Documentation/men-chameleon-bus.txt
> @@ -0,0 +1,162 @@
> + MEN Chameleon Bus
> + =================
> +
> +Table of Contents
> +=================
> +1 Introduction
> + 1.1 Scope of this Document
> + 1.2 Limitations of the current implementation
> +2 Architecture
> + 2.1 MEN Chameleon Bus
> + 2.2 Carrier Devices
> + 2.3 Parser
> +3 Resource handling
> + 3.1 Memory Resources
> + 3.2 IRQs
> +4 Writing a MCB driver
an
> + 4.1 The driver structure
> + 4.2 Probing and attaching
> + 4.3 Initializing the driver
> +
> +
> +1 Introduction
> +===============
> + This document describes the architecture and implementation of the MEN
> + Chameleon Bus (called MCB throughout this document).
What does "MEN" mean?
> +
> +1.1 Scope of this Document
> +---------------------------
> + This document is intended to be a short overview of the current
> + implementation and does by no means describe to complete possibilities of MCB
the
> + based devices.
> +
> +1.2 Limitations of the current implementation
> +----------------------------------------------
> + The current implementation is limited to PCI and PCIe based carrier devices
> + that only use a single memory resource and share the PCI legacy IRQ. Not
> + implemented are:
> + - Multi-resource MCB devices like the VME Controller or M-Module carrier.
> + - MCB devices that need another MCB device, like SRAM for a DMA Controller's
> + buffer descriptors or a video controller's video memory.
> + - A per-carrier IRQ domain for carrier devices that have one (or more) IRQs
> + per MCB device like PCIe based carriers with MSI or MSI-X support.
> +
> +2 Architecture
> +===============
> + MCB is divided in 3 functional blocks:
into
> + - The MEN Chameleon Bus itself,
> + - drivers for MCB Carrier Devices and
> + - the parser for the Chameleon table.
> +
> +2.1 MEN Chameleon Bus
> +----------------------
> + The MEN Chameleon Bus is an artificial bus system that attaches to an MEN
I would write "to a MEN" instead of "to an MEN", but I guess it depends on
whether one is reading it as a word (men) or 3 letters (M E N). I read it as
a word, so it's "to a MEN".
> + Chameleon FPGA device. These devices are multi-function devices implemented
> + in a single FPGA and usually attached via some sort of PCI or PCIe link. Each
> + FPGA contains a header section describing the content of the FPGA. The header
> + lists the device id, PCI BAR, offset from the beginning of the PCI BAR, size
> + in the FPGA, interrupt number and some other properties currently not handled
> + by the MCB implementation.
> +
> +2.2 Carrier Devices
> +--------------------
> + A carrier device is just an abstraction for the real world physical bus the
> + chameleon FPGA is attached to. Some IP Core drivers may need to interact with
> + properties of the carrier device (like querying the IRQ number of a PCI
> + device). To provide abstraction from the real hardware bus, an MCB carrier
> + device provides callback methods to translate the driver's MCB function calls
> + to hardware related function calls. For example a carrier device may
> + implement the get_irq() method which can be translate into a hardware bus
translated
> + query for the IRQ number the device should use.
> +
> +2.3 Parser
> +-----------
> + The parser reads the 1st 512 bytes of a chameleon device and parses the
first
Why sometimes capitalize Chameleon and sometimes not? What criteria do you
use to make that choice?
> + chameleon table. Currently the parser only supports the Chameleon v2 variant
> + of the chameleon table but can easily be adopted to support an older or
> + possible future variant. While parsing the table's entries new MCB devices
> + are allocated and their resources are assigned according to the resource
> + assignment in the chameleon table. After resource assignment is finished, the
> + MCB devices are registered at the MCB and thus at the driver core of the
> + Linux kernel.
> +
> +3 Resource handling
> +====================
> + The current implementation assigns exactly one memory and one IRQ resource
> + per MCB device. But this is likely going to change in the future.
> +
> +3.1 Memory Resources
> +---------------------
> + Each MCB device has exactly one memory resource, which can be requested from
> + the MCB bus. This memory resource is the physical address of the MCB device
> + inside the carrier and is intended to be passed to ioremap() and friends. It
> + is already requested from the kernel by calling request_mem_region().
> +
> +3.2 IRQs
> +---------
> + Each MCB device has exactly one IRQ resource, which can be requested from the
> + MCB bus. If a carrier device driver implements the ->get_irq() callback
> + method, the IRQ number assigned by the carrier device will be returned,
> + otherwise the IRQ number inside the chameleon table will be returned. This
> + number is suitable to be passed to request_irq().
> +
> +4 Writing a MCB driver
an
> +=======================
> +
> +4.1 The driver structure
> +-------------------------
> + Each MCB driver has a structure to identify the device driver as well as
> + device ids which identify the IP Core inside the FPGA. The driver structure
> + also contaings callback methods which get executed on driver probe and
contains
> + removal from the system.
> +
> +
> + static const struct mcb_device_id foo_ids[] = {
> + { .device = 0x123 },
> + { }
> + };
> + MODULE_DEVICE_TABLE(mcb, foo_ids);
> +
> + static struct mcb_driver foo_driver = {
> + driver = {
> + .name = "foo-bar",
> + .owner = THIS_MODULE,
> + },
> + .probe = foo_probe,
> + .remove = foo_remove,
> + .id_table = foo_ids,
> + };
> +
> +4.2 Probing and attaching
> +--------------------------
> + When a driver is loaded and the MCB devices it services are found, the MCB
> + core will call the driver's probe callback method. When the driver is removed
> + from the system, the MCB core will call the driver's remove callback method.
> +
> +
> + static init foo_probe(struct mcb_device *mdev, const struct mcb_device_id *id);
> + static void foo_remove(struct mcb_device *mdev);
> +
> +4.3 Initializing the driver
> +----------------------------
> + When the kernel is booted or your foo driver module is inserted, you have to
> + perform driver initialization. Usually it is enough to register your driver
> + module at the MCB core.
> +
> +
> + static int __init foo_init(void)
> + {
> + return mcb_register_driver(&foo_driver);
> + }
> + module_init(foo_init);
> +
> + static void __exit foo_exit(void)
> + {
> + mcb_unregister_driver(&foo_driver);
> + }
> + module_exit(foo_exit);
> +
> + The module_mcb_driver() macro can be used to reduce the above code.
> +
> +
> + module_mcb_driver(foo_driver);
--
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
