Messages in this thread | | | Date | Fri, 17 Jul 2015 20:16:49 +0000 | From | Johannes Thumshirn <> | Subject | Re: [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
| |