lkml.org 
[lkml]   [2015]   [Jul]   [17]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [PATCH v2] Documentation: Add MCB documentation
Zitat von Randy Dunlap <rdunlap@infradead.org>:

> On 07/17/15 03:23, Johannes Thumshirn wrote:
>> Add basic introductory documentation for the MEN Chameleon Bus.
>>
>> Signed-off-by: Johannes Thumshirn <jthumshirn@suse.de>
>> ---
>>
>> 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?
>

MEN is a company building this hardware. I guess this was a bit more
obvious when my emails ended on @men.de. Let me see how I can get this
information in there.

>> +
>> +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".

Now that you write it, I must admit it sounds more correct with "a".

>
>> + 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
>

Thanks for looking at it Randy.

For the remaining issues, do you want a v3 or a patch to the version
in the docs tree Jon?

Johannes



\
 
 \ /
  Last update: 2015-07-17 22:21    [W:0.416 / U:0.204 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site