MT 07-01.10. Beschreibung eines I2C Baums unter Embedded Linux

MT 07-01.10 Diplombericht Beschreibung eines I2C Baums unter Embedded Linux Abstract: Thesis topic is the evaluation and documentation of describing Single-Master I2C-topologies on Embedded-Linux containing Multiplexers and other I2C slave devices. Employing a prototype on a PowerPC based target, a mechanism of hiding the topology and its ease of integration are demonstrated. Keywords: I2C, Linux, Multiplexer, Flattened Device Tree, PowerPC Diplomand der Klasse 07-01: Christian Herzig, christian.herzig@keymile.com, 031 377 12 15 Experte: Rolf Lanz, rolf.lanz@bfh.ch, 031 848 32 73 Betreuer der Arbeit: Thomas Reufer, thomas.reufer@keymile.com, 031 377 11 24 Dieses Dokument ist Bestandteil der Thesis MT-07-01.10 10.09.2009 Christian Herzig

Zusammenfassung Ausgangslage Die Firma KEYMILE AG migriert Softwareprodukte von vxworks nach Embedded Linux. Ein bislang ungelöstes Problem ist die Behandlung der I2C-Schnittstelle. KEYMILE Produkte sind auf I2C-Multiplexer angewiesen. Durch diese ist das Ansprechen von mehreren Slaves mit identischer Adresse möglich. Bislang unterstützt der Linux Kernel keine I2C-Multiplexer. Zielsetzung Für die Firma KEYMILE AG gilt es, einen Vorschlag auszuarbeiten, wie Single Master I2C- Baumstrukturen mit verschiedenen Slave-Typen unter Embedded Linux beschrieben werden. Mit einem auf einer PowerPC Architektur basierten Prototypen wird die entwickelte Lösung demonstriert. Vorgehensweise Um schlussendlich zum funktionierenden Prototypen zu gelangen, wird die bestehende Lösung unter vxworks analysiert. Die Ergebnisse dieser Analyse bilden die Grundlage für das Formulieren der Anforderungen an die I2C-Lösung unter Embedded Linux. Vor- und Nachteile der möglichen Lösungsansätzen werden gegenübergestellt und der vielversprechendste Ansatz gewählt. Die Realisierung des Prototypen erfolgt strukturiert in verschiedenen Etappen. Zum Schluss wird der Prototyp dem Abnahmetest unterzogen. Alle Schritte und Zwischenlösungen sind dokumentiert. Prototyp Aus der Arbeit MT-07-01.10 resultiert ein Prototyp, der allen Anforderungen gerecht wird. Die Aufgabe ist unter Verfolgung der Linux-Konzepte vollständig gelöst. Die erlangte Lösung umfasst einige Kernel-Patches, welche die Behandlung von Multiplexern im Linux-Kernel ermöglichen. Alle am I2C-Kontroller angeschlossenen Bauteile sind über ein virtuelles Filesystem ansprechbar. Dabei verbirgt das System dem Benutzer die Baumstruktur. Die Schaltung der I2C-Multiplexer erfolgt ohne Benutzerinteraktion durch den Kernel. Eine im Rahmen der Master-Thesis erstellte Software-Komponente bietet ein API, um auf die I2C-Komponenten zuzugreifen. Kleine Programme zu Informations- oder Demonstrationszwecken sind in dieser Komponente integriert und per Command Line Interface via serielles Terminal oder Telnet ausführbar. Eine umfassende Sammlung an CUnit Testfällen rundet diese Komponente ab. Fazit In der vorliegenden Arbeit wird eine elegante Lösung präsentiert. Die Beschreibung der I2C- Baumstruktur lässt sich in die bestehende Hardware-Abstraktion integrieren. Mit dem Projektschluss sind ein funktionierender Prototyp und diverse Dokumente verfügbar. Alle mit höchster Priorität (A) deklarierten Anforderungen sind vom Prototypen erfüllt. Rund drei Viertel aller B-priorisierten Anforderungen sind ebenfalls erfüllt. Die Umsetzungsquote der Anforderungen mit der niedrigsten Priorität beträgt 30%. Alle nicht erfüllten Anforderungen sind in der Analyse berücksichtigt, aber aus zeitlichen Gründen nicht implementiert. 10.09.2009 Seite i Christian Herzig

Inhalt Zusammenfassung...i Ausgangslage...i Zielsetzung...i Vorgehensweise...i Prototyp...i Fazit...i Inhalt...ii 1 Einleitung... 1 1.1 Zweck des Dokuments... 1 1.2 Leserkreis... 1 1.3 Auftraggeber... 1 1.4 Zielsetzung... 1 1.5 Vorgehensweise... 2 1.5.1 Analyse der vxworks Lösung... 2 1.5.2 Anforderungen an die Linux Lösung... 2 1.5.3 Vorschläge für die Implementierung... 2 1.5.4 Implementierung... 2 1.5.5 Test... 2 2 Projektmanagement... 3 2.1 Projektorganisation... 3 2.2 Zeitplanung/Projektphasen... 3 2.3 Anforderungen... 3 2.4 Statusberichte... 3 2.5 Meetings... 3 2.6 Reviews... 3 3 Überblick der Software... 4 4 Das Linux I2C-Subsystem... 5 4.1 I2C-Adapter... 5 4.2 I2C-Treiber... 6 4.3 I2C-Clients... 6 4.4 Übersicht... 7 5 Analyse und Inbetriebnahme... 8 5.1 Adapter und Clients registrieren... 8 5.2 Virtuelle Adapter... 9 5.3 Profitieren von Open Source... 9 5.4 Erweitern des PCA954x Treibers...10 5.5 Anbinden von Clients an den Multiplexer...10 5.5.1 Statische Instanzierung...10 5.5.2 Instanzierung anhand des Device Trees...11 6 Realisierung im Kernel...12 6.1 Repositoy...12 6.2 Patches von der Firma KEYMILE...12 6.3 Patches von Rodolfo Giometti...12 6.4 Ausgangslage...13 6.5 Patches für die Diplomarbeit...13 6.5.1 Patch 0022...13 6.5.2 Patch 0023...13 6.5.3 Patch 0024...13 10.09.2009 Seite ii Christian Herzig

6.5.4 Patch 0025...13 6.5.5 Patch 0026...13 6.5.6 Patch 0027...13 6.5.7 Patch 0028...13 7 Komponente LINUXI2C...14 7.1 Kontext...14 7.2 Sinn und Zweck...14 7.3 Repository...14 7.4 Struktur der Komponente...14 7.5 Design...15 7.6 I2C API...17 7.6.1 Service EEPROM...17 7.6.2 Service IVM...19 7.6.3 Service Temp...20 7.7 List-Stimuli...21 8 Instruktionen zum Prototypen...23 8.1 Zielgruppe...23 8.2 Flattened Device Tree...23 8.2.1 I2C-Kontroller...23 8.2.2 I2C-Slaves am I2C-Kontroller...24 8.2.3 I2C-Mux am I2C Kontroller...24 8.2.4 Am I2C-Mux angeschlossene I2C-Slaves...25 8.2.5 Kaskadierte Multiplexer...25 8.2.6 Häufige Fehler...27 8.3 Dynamische Vergabe der I2C Device- und Adapternamen...27 8.4 Linuxi2c Komponente...28 8.4.1 Installation...28 8.4.2 Services...29 8.4.3 Stimuli...30 8.4.4 CUnit Test...30 8.4.5 Erweitern der Linuxi2c Komponente...31 9 Linux I2C Test Tools...33 10 Arbeiten in der Linux Community...34 10.1 Mailinglisten...34 10.2 Git Repository...34 10.3 Patches erstellen...34 10.4 Patches prüfen...34 10.5 Patches versenden...35 10.6 Wie Patches in die Mainline gelangen...35 11 Teststrategie...36 11.1 Review von Dokumenten...36 11.2 Review von Codes...36 11.3 Regression Test...36 11.4 Validierung...36 12 Resultate des Abnahmetests...37 12.1 Testaufbau...37 12.2 Geltungsbereich...37 12.3 Funktionen...37 12.4 Programmierung...38 12.5 Installation...38 12.6 Fehler...39 10.09.2009 Seite iii Christian Herzig

12.7 Dokumentation...39 12.8 Stimuli / Servicekanal...40 12.9 Initialisierung...40 12.10 Verschiedenes...41 12.11 Datenbasis...41 12.12 Tutorial...42 12.13 Performanz...42 12.14 Test...42 13 Ausblick...43 14 Danksagung...43 15 Abkürzungen, Begriffe und Namen...44 16 Abbildungsverzeichnis...45 17 Verzeichnis der Listings...46 18 Verzeichnis der Tracings...46 19 Literaturverzeichnis...47 20 Historie...47 A Anhang...48 A.1 Strukturen und Relationen im I2C Subsystem...48 A.2 Vollständiges DTS File für die ETER1 Hardware:...49 B Sequenzdiagramme der LINUXI2C Komponente...56 10.09.2009 Seite iv Christian Herzig

1 Einleitung 1.1 Zweck des Dokuments Dieses Dokument beinhaltet den Schlussbericht der Master-Thesis MT-07-01.10, Beschreibung eines I2C Baums unter Embedded Linux, welche im Sommer-Semester 2009 zwischen März und September von Christian Herzig erstellt wurde. Der Bericht dokumentiert den Ablauf der Arbeit und erläutert die erreichten Lösungen. Somit wird die Nachverfolgbarkeit sichergestellt sowie Möglichkeiten und Ansätze zur Weiterentwicklung geliefert. Die Zusammenfassung der erfüllten Anforderungen ist ebenfalls Bestandteil des Dokuments und am Schluss zu finden. 1.2 Leserkreis Dieses Dokument richtet sich primär an den Experten und den Betreuer der Master Thesis MT-07-01.10. Weiter liefert dieses Dokument hilfreiche Informationen für die Software-Entwickler der Firma KEYMILE AG, welche für die Linux-Plattform verantwortlich sind. Das Kapitel 8.2 bietet für die Hardware Entwickler wichtige Hinweise zur Erstellung der Datenbasis für den I2Crelevanten Teil. Grundkenntnisse von Linux, vom Linux-Kernel und I2C sind Voraussetzung, um den Inhalt dieses Dokuments und den Kontext der Problemstellung zu verstehen. Fundiertes Linux- Basiswissen kann aus den Quellen [4], [5] und [6] erlangt werden. Für die I2C-Grundlagen wird auf das Kapitel 3 in [1] verwiesen. Die Dokumente Beschreibung der I2C Topologie unter vxworks [1], Anforderungen an die Implementation unter Linux [2] und das Dokument Vorschlag für die I2C Implementierung unter Linux [3] sind ebenfalls Resultate dieser Diplomarbeit und bilden die Grundlage dieses Berichts. 1.3 Auftraggeber Auftraggeber ist die Firma KEYMILE AG. Die in dieser Diplomarbeit erlangten Erkenntnisse und Lösungen fliessen in die Weiterentwicklung der KEYMILE Embedded Linux Software Plattform der Produktefamilien UMUX und Milegate ein. UMUX und Milegate sind Multiservice Plattformen für Telekom-Netzbetreiber und stellen das Vermittlungsstück zwischen WAN und den Endbenutzern dar. Die durch diese Produkte unterstützten Dienste reichen von Telefonie über xdsl bis hin zu FTTx. Weiter finden diese Plattformen aufgrund ihrer hohen Verfügbarkeit Einsatz im Bereich des Schienenverkehrs, der Überwachung und Steuerung von Energiewerken und ähnlichen sicherheitsrelevanten Anwendungen. Die Multiservice Plattformen unterstützen hierbei eine Vielzahl von Teilnehmerschnittstellen, von V.24 bis GbE. Die Anbindung an das Backbone-Netz erfolgt wahlweise über GbE oder STM-1/STM-4. 1.4 Zielsetzung Für die Firma KEYMILE AG gilt es, einen Vorschlag auszuarbeiten, wie Single Master I2C- Baumstrukturen mit verschiedenen Slave-Typen unter Embedded Linux beschrieben werden. Mit einem auf einer PowerPC Architektur basierten Prototypen wird die entwickelte Lösung demonstriert. 10.09.2009 Seite 1 Christian Herzig

1.5 Vorgehensweise Nach Absprache mit dem Betreuer wird die Vorgehensweise selbst definiert und den Anforderungen angepasst. Einzig die Definition der Anforderungen an den im Rahmen der Diplomarbeit erstellten Prototypen, ist durch die Berner Fachhochschule vorgeschrieben. 1.5.1 Analyse der vxworks Lösung Die Anforderungen der Firma KEYMILE AG an das I2C-System in den Embedded Produkten sind mit einer Analyse der bestehenden vxworks Lösung erfasst. 1.5.2 Anforderungen an die Linux Lösung Die Resultate der Analyse dienen als Grundlage für das Aufstellen der Anforderungen an die KEYMILE Produkte. Aus diesen Anforderungen wird ein Subset gewählt, welches im Rahmen der Diplomarbeit anhand eines Prototypen umgesetzt werden soll. Der Anforderungskatalog für den Prototypen wurde am 25. Mai 2009 auf die Diplomplattform hochgeladen und durch den Experten freigegeben. 1.5.3 Vorschläge für die Implementierung Ein weiteres Dokument [3] zeigt die einzelnen Lösungsansätze auf. Die einzelnen Ansätze sind darin bewertet, die Vor- und Nachteile aufgeführt. Aus diesem Dokument resultiert derjenige Vorschlag, der für die Firma KEYMILE AG den grösstmöglichen Nutzen bringt. 1.5.4 Implementierung Die Implementierung erfolgt schrittweise. Das I2C-System des Linux Kernels wird in Betrieb genommen, indem für den Hardware Kontroller der korrespondierende Adapter-Treiber geladen wird. Ein EEPROM- und ein Temperatur-Sensor-Treiber werden geladen und beide Clients beim Adapter angemeldet. In einem weiteren Schritt werden die Patches für die Multiplexer Unterstützung, ein PCA954x Device-Treiber und das Multiplexer Herzstück, welches virtuelle I2C-Adapter beim Kernel anmeldet, auf den KEYMILE Linux Kernel portiert. Der Multiplexer Device-Treiber wird mit einem Attribut ergänzt. Die Funktionalität und die Praxistauglichkeit des Multiplexer- Herzstücks werden mit Open Source I2C-Tools geprüft. Ist das Instanzieren und Anbinden der Clients an die virtuellen Adapter geglückt, folgt die Implementation, welche das Laden und Registrieren der Device Treiber anhand der Datenbasis ermöglicht. Parallel zu den Implementierungen im Linux Kernel wird ein KEYMILE-API erstellt. Das API wird in Form einer KEYMILE Team-Komponente implementiert, welche einerseits ein API für den Zugriff auf die I2C-Komponenten, andererseits auch Testfunktionen und CUnit Testfälle umfasst. Dokumentiert ist diese Komponente mit Doxygen [7]. 1.5.5 Test Für die Team-Komponente sind CUnit Testfälle definiert und implementiert. Der Prototyp ist validiert. Die Test Resultate sind am Schluss dieses Berichts zusammengefasst. 10.09.2009 Seite 2 Christian Herzig

2 Projektmanagement 2.1 Projektorganisation Die Diplomarbeit ist eine Einzelarbeit. 2.2 Zeitplanung/Projektphasen Die Arbeit ist zu Beginn in die folgenden Projektphasen mit jeweiliger Aufwandschätzung aufgeteilt worden: - Kickoff, Projektmanagement (7 %) - Analyse der Implementierung unter vxworks (10 %) - Erstellung der Anforderungen an Embedded Linux für KEYMILE AG (15 %) - Vorschläge der Implementierung für KEYMILE AG (25 %) - Erstellung der Anforderungen an den Master Thesis Prototypen (10 %) - Realisierung des Prototypen, Test und Dokumentation (30 %) - Präsentation (3 %) Ausführungen zur effektiv benötigten Zeit: Die proportionale Verteilung der Aufwände stimmt mit der schlussendlich benötigten Zeit überein. Der Gesamtaufwand der Arbeit von etwa 600 geleisteten Stunden wurde mit Faktor 1,5 unterschätzt. Aus der Sicht des Projektleiters musste zur Korrektur früh eine Entscheidung getroffen werden. Mögliche Korrekturmassnahmen waren, mehr Aufwand in die Diplomarbeit zu investieren oder die Anforderungen zu reduzieren. Die Entscheidung fiel zugunsten des Projekts und der Mehraufwand wurde während geplanter Ferienzeit geleistet. 2.3 Anforderungen Die Anforderungen an die I2C-Lösung unter Embedded Linux wurden mit den Anforderungen an den Prototypen zusammengelegt und in einem Dokument abgehandelt [zip]. 2.4 Statusberichte In Abständen von 10 bis 20 Arbeitstagen wurde dem Experten und dem Betreuer der Status der Diplomarbeit in schriftlicher Form mitgeteilt. Insgesamt sind neun Statusberichte verfasst worden [zip]. 2.5 Meetings Während der Diplomarbeit fanden insgesamt vier Meetings mit dem Experten statt. Zu Beginn der Arbeit erfolgte das Kickoff Meeting an der Software Schule, zum Schluss der Arbeit die Abnahme in der Firma KEYMILE AG. Zwischenzeitlich fanden zwei weitere Treffen an der Softwareschule statt, in denen hauptsächlich inhaltliche Aspekte der Dokumentation diskutiert wurden. Mit dem Betreuer waren wöchentlich Sitzungen eingeplant. Dabei wurden Vorgehensweise und weitere Schritte besprochen. 2.6 Reviews Sämtliche während dieser Arbeit entstandenen Dokumente wurden einem Review unterzogen. 10.09.2009 Seite 3 Christian Herzig

3 Überblick der Software Dieser Diplombericht behandelt zwei unabhängige Software-Teile. Abbildung 1: Software Übersicht Der grün gekennzeichnete Kernel-Software-Teil wird in den Kapitel 4, 5 und 6 behandelt. Auf den Aufbau und die Funktionalität der LINUXI2C Komponente, in der Abbildung 1 gelb gekennzeichnet, wird detaillierter in Kapitel 7 eingegangen. 10.09.2009 Seite 4 Christian Herzig

4 Das Linux I2C-Subsystem Die nachfolgenden Kapitel erklären, wie das I2C-Subsystem aufgebaut ist und erläutern weiterhin die Linux Terminologie. User Kernel client n 1 adapter n 1 1 driver 1 HW Abbildung 2: Zusammenhang der einzelnen I2C Teile Jeder physikalische I2C Slave Baustein wird durch ein struct client repräsentiert. Verschiedene Bausteine desselben Typs teilen sich einen Driver, repräsentiert durch das struct driver. Der Adapter sorgt für die Kommunikation zwischen Kernel und Hardware. 4.1 I2C-Adapter I2C-Adapter übernehmen die Master Funktion des I2C-Busses. Für die Prototyp Hardware wird ein MPC Adapter benötigt. Dieser Treiber wurde für die I2C-Kontroller von Freescale geschrieben. Der Name MPC ist historisch bedingt und steht für Motorola PowerPC. Die Motorola Halbleiter-Abteilung wurde im Jahr 2004 ausgegliedert, woraus die Firma Freescale Semiconductors entstand. Im Linux Kernel wird ein I2C-Adapter durch das struct i2c_adapter repräsentiert. class mpc_i2c «/sys/class/i2c_adapter» i2c_adapter device - *owner: struct module - id: int - class: int - *algo: struct i2c_algorithm - *algo_data: void - dev: struct device - nr: int - name: char[] - dev_released: struct completion mpc_i2c - *dev: struct device - interrupt: u32 - irq: int - adap: struct i2c_adapter Abbildung 3: struct mpc_i2c erbt von i2c_adapter Für die Registrierung des Adapters beim Kernel wird die i2c-core Funktion i2c_add_adapter()aufgerufen, welche das initialisierte struct i2c_adapter als Parameter übergibt. Der Adapter bezieht vom Kernel seine ID und registriert sich mit der Funktion i2c_register_adapter() beim Kernel. 10.09.2009 Seite 5 Christian Herzig

4.2 I2C-Treiber Für jede Art von I2C-Slaves wird ein entsprechender Treiber geladen. I2C-Treiber übernehmen die Funktion der I2C-Slaves. Beim Hardware-Prototyp kommen LM75 (Temperatur Sensor), 24C08 (1KiB EEPROM) und PCA9547 (8-Kanal Multiplexer) zum Einsatz. Die korrespondierenden Treiber sind lm75 aus dem Linux Hardware Monitoring- Package, at24 für das EEPROM und der neu in der Arbeit hinzugefügte pca954x Multiplexer- Treiber. Das struct i2c_driver repräsentiert im Linux Kernel die I2C-Treiber. class Domain Model «/sys/bus/i2c/drivers» i2c_driv er - id: int - driver: struct device_driver - *id_table: struct i2c_device - clients: int + attach_adapter() + detach_adapter() + probe() + remove() + resume() + shutdown() Abbildung 4: struct i2c_driver Die i2c-core Funktion i2c_register_driver() registriert den Treiber beim Kernel. Der lm75 Treiber für den Temperatur Sensor ist zuständig für das Auslesen des Temperatur- Registers und dessen Darstellung im sysfs. Weiter ermöglicht der Treiber das Schreiben und Lesen des Hyst-Registers, welches die Schaltschwelle bei der Thermostatfunktion vorgibt. Der at24 EEPROM Treiber unterstützt eine Vielzahl von I2C EEPROMs diverser Grössen. Der Treiber repräsentiert im sysfs ein File mit der Grösse des Speicherinhaltes, auf welches lesend und schreibend zugegriffen werden kann. Der Multiplexer Treiber pca954x bewerkstelligt die Kanal-Schaltung. 4.3 I2C-Clients Für jeden physikalischen I2C-Slave Baustein existiert ein I2C-Client Objekt im Kernel. Die Bezeichnung Client bezieht sich hierbei auf die Beziehung zum Treiber. Jeder I2C-Client wird durch ein struct i2c_client repräsentiert. class Domain Model dev ice dev_archdata - *parent: struct device - *p: struct device_private - kobj: struct kobject - *init_name: const char - *type: struct device_type - sem: struct semaphore - *bus: struct bus_type - *driver: struct device_driver - *driver_data: void - *platform_data: void - power: struct dev_pm_info - archdata: struct dev_archdata «/sws/bus/i2c/devices/» i2c_client - flags: unsigned short - addr: unsigned short - name: char[] - *adapter: struct i2c_adapter - *driver: struct i2c_driver - dev: struct device - irq: int Abbildung 5: struct i2c_client erbt von device Die i2c-core Funktion i2c_attach_client() schliesst den Client beim Adapter an. 10.09.2009 Seite 6 Christian Herzig

4.4 Übersicht Die I2C-Subsystem Übersicht aus dem Dokument der Implementierungsvorschläge [3] wurde um die in der vorliegenden Arbeit neu hinzugekommenen Komponenten ergänzt. Blau gekennzeichnet sind die Patches von Rodolfo Giometti [11]. Durch den Studenten modifizierte Teile des Kernels sind in oranger Farbe gehalten. User Kernel HW Abbildung 6: Aufbau des I2C-Subsystems mit den neuen Komponenten Neues und zugleich zentrales Element im I2C-Subsystem ist der I2C-Mux (i2c-mux.c). Dieser Teil ermöglicht es, I2C-Bussegmente als eigenständige I2C-Adapter abzubilden. Der Device-Treiber PCA954x übernimmt die Kontrolle der I2C-Multiplexer und I2C-Switches der PCA954x Produktefamilie der Firma Philips. Die Unterstützung der I2C-Multiplexer- Funktionalität lässt sich im Kernel konfigurieren. Der I2C-Teil des Open Firmware Treibers wird angepasst, um anhand der Datenbasis die Treiber zu laden. Eine Anleitung, wie die Kind-Knoten eines Multiplexers beschrieben werden, ist der Kernel Dokumentation hinzugefügt. 10.09.2009 Seite 7 Christian Herzig

5 Analyse und Inbetriebnahme Eine erste Herausforderung bestand darin, bestehende Abläufe im Kernel zu analysieren. Hierauf basiert ein Ansatz zur Problemlösung. Soweit nicht anders spezifiziert, ist in diesem Dokument unter dem Begriff Kernel der KEYMILE Kernel, einem Stand der auf der Version 2.6.28 basiert, zu verstehen. 5.1 Adapter und Clients registrieren Eines der Ziele [3] dieser Arbeit ist die Beschreibung der I2C-Hardware-Struktur im Flattened Device Tree [8]. Um die Mechanismen im Kernel zu erfassen, wird zunächst der zweite I2C- Kontroller des Entwicklungs-Zielsystems mit seinen Slaves, einem LM75 Temperatur Sensor und einem AT24 kompatiblen EEPROM, in Betrieb genommen. Obwohl die Kernel-Sourcen in der Programmiersprache C geschrieben sind, und es keine eigentlichen Klassen im Objekt orientierten Sinne gibt, verwendet der Autor zur Veranschaulichung von Abläufen Sequenzdiagramme. Die Abbildung 7 zeigt den typischen Ablauf beim Registrieren des I2C-Adapters und der I2C- Devices beim Kernel. Als Einstiegspunkt dient die fsl_i2c_probe() Funktion des MPC Adapter-Treibers. sd fsl_i2c_probe i2c_mpc DEVICE TREE of_i2c KERNEL i2c-core irq_of_parse_and_map(node) of_get_property(dfsrr) Das struct i2c_adapter wird anhand des Device Trees initialisiert i2c_add_adapter() of_register_i2c_devices() register_adapter() Dieser Vorgang wird gilt für jeden Kindknoten des Adapters durchgeführt of_get_property(reg) request_module() i2c_new_device() attach_client() Abbildung 7: Registrieren vom I2C-Adapter und dessen Clients Während des Ladevorgangs des I2C-Adapters werden die Properties vom Adapter-Knoten ausgelesen und den entsprechenden Feldern im neu instanzierten struct mpc_i2c zugewiesen. 10.09.2009 Seite 8 Christian Herzig

class mpc_i2c «/sys/class/i2c_adapter» i2c_adapter device - *owner: struct module - id: int - class: int - *algo: struct i2c_algorithm - *algo_data: void - dev: struct device - nr: int - name: char[] - dev_released: struct completion mpc_i2c - *dev: struct device - interrupt: u32 - irq: int - adap: struct i2c_adapter Abbildung 8: Die mpc_i2c Struktur Der im mpc_i2c enthaltene i2c-adapter wird zum i2c-core addiert. Gelingt es dem i2c-core, den Adapter beim Kernel zu registrieren, wird für jeden Kind-Knoten im Device Tree der entsprechende I2C-Device-Treiber geladen und beim Kernel angemeldet. Mit dieser Erkenntnis ist es möglich, den zweiten I2C-Kontroller mit seinen direkten Slaves in Betrieb zu nehmen. Dafür müssen in der Kernel Configuration der MPC-Adapter Treiber, die Device-Treiber für den Temperatur Sensor LM75 und der Device-Treiber für die AT24 kompatiblen EEPROMs aktiviert werden. In den Kernel Sourcen [9] sind die DTS-Bindings für den LM75 und den AT24 zu finden. Mit diesen Bindings lassen sich die beiden I2C-Devices beschreiben und auf der Testhardware in Betrieb nehmen. 5.2 Virtuelle Adapter Unter vxworks [1] wird der I2C Multiplexer wie ein I2C-Slave angesehen und auch als solcher behandelt. Ein anderer Ansatz ist, den I2C-Multiplexer nicht als Client zu betrachten, sondern jeden Kanal des Multiplexers als eigenständigen virtuellen I2C-Adapter zu modellieren. Die Idee der virtuellen Adapter [3, Kapitel 7.2] ist nicht neu. Dieser Ansatz liess sich bei Recherchen im Internet bis ins Jahr 2003 zurückverfolgen [10]. 2006 überarbeitete Kumar Gala die bewährte Lösung [19] und portierte diese auf den Kernel 2.6.14. Im März 2009 hat sich Rodolfo Giometti diesem Projekt erneut angenommen und portierte die Patches auf den Kernel 2.6.29 [11]. Das I2C-Subsystem ist relativ neu und wurde erst zu Zeiten des Kernels 2.0 dem offiziellen Kernel-Tree hinzugefügt. Einige Spezialitäten der Treiberstruktur hatten immer wieder grundlegende Änderungen an den Schnittstellen des I2C-Subsystems zur Folge. In den letzten Monaten wurde daran gearbeitet, das I2C-Subsystem bestehenden Linux-Konzepten anzupassen. Diese Verbesserungen liegen zurzeit als Patch-Serie vor und werden aller Wahrscheinlichkeit nach in die nächsten offiziellen Kernel einfliessen. Die aktuelle Kernel Version zum Zeitpunkt des Erstellens dieses Berichts ist die Version 2.6.30.5. 5.3 Profitieren von Open Source Gestützt auf die Tatsache, dass der Ansatz der virtuellen Adapter wiederholt aufgegriffen wurde, fiel die Entscheidung, die vorliegende Arbeit basierend auf den bestehenden Patches fortzuführen. Das Git-Repository von Giometti [11] wurde geklont, Patches daraus extrahiert und auf den KEYMILE-Kernel appliziert. Es folgte eine weitere Analyse des Codes. 10.09.2009 Seite 9 Christian Herzig

Wie aus Abbildung 7 zu entnehmen ist, wird der Multiplexer PCA954x wie jeder andere I2C- Client instanziert und angebunden. Das folgende Sequenzdiagramm zeigt, was beim Laden des Multiplexer Device-Treibers geschieht. sd PCA954x probe pca954x probe i2c-mux i2c-core i2c_add_mux_adapter() new i2c_mux_priv() i2c_add_adapter() Sequenz für jeden Multiplexer Kanal i2c_register_adapter() Abbildung 9: Laden des Multiplexer-Treibers und Registrieren der virtuellen Adapter Für jeden Multiplexer-Kanal wird die Funktion i2c_add_mux_adapter() aufgerufen. In dieser Funktion wird ein neuer I2C-Adapter instanziert, beim i2c-core angemeldet und registriert. Mit den Kenntnissen über den Ablauf der Instanzierung der bereits integrierten Device- Treiber ist nun auch das Instanzieren und Anbinden des PCA954x an den ersten I2C Kontroller möglich. Nach der Behebung zweier Fehler lässt sich der PCA954x Client auf dem Testboard in Betrieb nehmen. Erwartungsgemäss wird jeder Kanal durch einen separaten I2C-Adapter abgebildet, was sich im sysfs überprüfen lässt. 5.4 Erweitern des PCA954x Treibers Um die Funktionalität, also die Schaltung des Multiplexers, zu prüfen, ist dem Treiber das channel Attribut hinzugefügt worden. Dadurch ist es neu möglich, direkt aus dem sysfs den aktiven Kanal auszulesen. Mit dem Einsatz von diversen I2C-Tools (siehe Kapitel 9) kann die Funktionalität und die Praxistauglichkeit dieser Patches verifiziert werden. 5.5 Anbinden von Clients an den Multiplexer In der Folge werden die Clients hinter dem Multiplexer in Betrieb genommen. 5.5.1 Statische Instanzierung Die Instanzierung der Clients erfolgt in einem ersten Schritt statisch. Für jedes I2C-Segment wird ein Array von i2c_board_info definiert und mit i2c_register_board_info() beim Kernel registriert. 10.09.2009 Seite 10 Christian Herzig

5.5.2 Instanzierung anhand des Device Trees Das Anbinden von Clients an die virtuellen I2C-Adapter erfordert aufgrund der neuen virtuellen Adapter eine Modifikation des pca954x Treibers sowie die Implementation einer neuen Methode (Abbildung 10) im Open Firmware Teil von I2C. Für jeden Kind-Knoten wiederhole: lese Mux-Kanal aus dem Knoten ja richtiger Kanal? nein initialisiere Variabeln lese Knoten-Typ ja erfolgreich? nein lese Knoten-Adresse ja erfolgreich? nein behandle IRQ registriere device struct in archdata melde Modul an ja erfolgreich? instanziere I2C-Device entferne IRQ nein Abbildung 10: Diagramm der Funktion of_register_devices_behind_muxes() Das folgende Diagramm zeigt, wie Clients an einen virtuellen Adapter angeschlossen werden: sd pca954x probe pca954x device i2c-core of_i2c DEVICE TREE KERNEL dev_archdata_get_node() i2c_get_adapter() Sequenz für jeden Multiplexer Kanal of_register_i2c_devices_behind_muxes() of_get_property(reg) Sequenz für jeden Kind-Knoten of_register_i2c_device() request_module() i2c_new_device() Abbildung 11: Instanzieren und Anschliessen von Clients anhand des Device Trees 10.09.2009 Seite 11 Christian Herzig

6 Realisierung im Kernel Wie im Dokument Vorschläge für die Implementierung [3] beschrieben, wird die Schaltlogik für die Multiplexer im Linux-Kernel realisiert. Die Beschreibung der Hardware erfolgt im Flattened Device Tree [8]. 6.1 Repositoy Als Kernel Source Grundlagen dienen folgende Git Repositories: git://srv-esw-gitrepos/esw_gitrepos/linux-2.6-km.git git://git.enneenne.com/linux_i2c_mux Im Keymile Git Repository sind die Kernel Quellen für die ETER1 abgelegt. Das Git Repository von Rodolfo Giometti enthält den I2C-Multiplexer Support für Linux Kernel 2.6.29. 6.2 Patches von der Firma KEYMILE Als Basis für den Kernel des Produkts ETER1 wird der KEYMILE Git Tag KEYMILEv2.6.28-dev-3.1.0 verwendet. Dieser Kernelstand muss um die Patches 0001 bis 0012 ergänzt werden, damit die Applikation funktioniert [zip]. Weil diese Patches für I2C irrelevant sind, wird an dieser Stelle nicht weiter darauf eingegangen. 6.3 Patches von Rodolfo Giometti Aus dem Git-Repository lassen sich Patches folgendermassen extrahieren: ~$ git format-patch s origin/head Die Patches von Giometti [11] erweitern den Kernel folgendermassen: 0013- Entfernt die driver_unregister() Funktion aus dem durch den core_lock Mutex geschützten Bereich [zip]. 0014- Während der Registrierung der I2C-Adapter wird die Funktion i2c_scan_static_board_info() aufgerufen, welche bislang durch einen Mutex geschützt ist. Sobald Multiplexer kaskadiert werden, erfolgt der Aufruf dieser Funktion rekursiv, was der bisherig verwendete Mutex verhinderte. Der Patch ersetzt den Mutex durch ein rwsem-locking, welches gleichzeitigen Schreibzugriff verhindert, jedoch gleichzeitigen Lesezugriff erlaubt [zip]. 0015- Das Deregistrieren von I2C-Adaptern kann durch alte Legacy-Treiber verhindert werden. Dieser Patch ignoriert, wenn ein Legacy-Treiber während des Deregistrierens noch aktiv sein sollte. Dieser Punkt tangiert die Arbeit MT-07-01.10 nicht, da keine Legacy-Treiber zum Einsatz kommen [zip]. 0016- Der globale core_lock Mutex wird durch einen eigenen Mutex für die Adapter Registrierung und Deregistrierung eingesetzt. Dies ermöglicht das rekursive Registrieren und Deregistrieren von realen und virtuellen I2C Adaptern [zip]. 0017- Fügt die eigentliche Funktionalität hinzu. Der Patch ermöglicht dem i2c-core, die einzelnen I2C-Segmente als I2C-Adapter zu präsentieren. Der neue Code umfasst die Logik im i2c-mux.c File sowie die dazugehörigen einträge im Makefile sowie einem neuen Menüpunkt für die Kernel Konfiguration [zip]. 0018- Der Device-Treiber für die PCA954x Produktefamilie. Dieser Treiber unterstützt sowohl I2C-Switches wie auch I2C-Multiplexer [zip]. 0019- Ändert die Lizenz des Treibers von GPL nach GPL v2 [zip]. 10.09.2009 Seite 12 Christian Herzig

6.4 Ausgangslage Die Arbeit von Giometti war Einstiegspunkt für das Weiterführen der Arbeit. Auf diesem Stand setzt die Arbeit des Studenten auf. Erst wurden zwei Fehler in Giomettis Code korrigiert: 0020- Die Arraydefinition für die verschiedenen PCA954x DeviceTypen wurde fehlerhaft initialisiert [zip]. 0021- Beim laden des PCA954x Treibers gab es einen Absturz des Kernels, verursacht durch die Dereferenzierung eines NULL-Pointers. Der Patch prüft erst den Wert des Pointers [zip]. 6.5 Patches für die Diplomarbeit 6.5.1 Patch 0022 Zur Überprüfung ob sich der Multiplexer wie erwartet verhält, wird dem Treiber ein channel Attribut hinzugefügt. Dadurch ist es möglich, aus dem sysfs direkt den aktiven Kanal auszulesen. Die Rechte auf das Attribut sind read only [zip]. 6.5.2 Patch 0023 Das Device Tree Source File wird mit den I2C-Knoten für die I2C-Adapter und Clients ergänzt. Der Patch ist Prototypen-Hardware spezifisch [zip]. 6.5.3 Patch 0024 Dieser Patch veranlasst den PCA954x Treiber, nach dem Laden des Treibers in dem Device Tree nach Kind-Knoten zu suchen und die darin spezifizierten Treiber zu laden [zip]. 6.5.4 Patch 0025 Der I2C spezifische Open Firmware Treiber wird um eine neue Funktion für die Behandlung der Multiplexer Kind-Knoten ergänzt. Im Header File wird diese deklariert. Die zweite neue Funktion wird eingeführt, um Code-Redundanz zu vermeiden [zip]. 6.5.5 Patch 0026 Dieser Patch liefert die Implementation der Deklaration von Patch 0025. Der I2C spezifische Open Firmware Treiber behandelt die Multiplexer Kind-Knoten. Die zweite Funktion dient der Verhinderung von Code-Redundanz [zip]. 6.5.6 Patch 0027 Neu werden vom Kernel diverse I2C Funktionalitäten verlangt. Zur bisherigen ETER1 Kernel- Konfiguration kommen der I2C Multiplexer Support hinzu, der Treiber für die AT24 Familie und der Treiber für den LM75 Sensor. Zusätzlich sind die I2C-Debug Features aktiviert [zip]. 6.5.7 Patch 0028 Dieser Patch fügt der Kernel Dokumentation eine Anleitung hinzu, wie der Multiplexer- Knoten und die Multiplexer Kind-Knoten im Flattened Device Tree beschrieben werden [zip]. 10.09.2009 Seite 13 Christian Herzig

7 Komponente LINUXI2C 7.1 Kontext Software, welche klar definierte Schnittstellen aufweist, ein abgeschlossenes Problem behandelt und für eine Wiederverwendung in Betracht gezogen wird, wird in der Firma KEYMILE Komponente genannt. KEYMILE unterscheidet dabei zwei Arten: Plattform-Komponenten kommen in jedem Software Produkt zum Einsatz und bieten generische Dienste an. Produkt-Komponenten werden je nach Produkte Gruppe in ein Produkt integriert. Abbildung 12: Kontext der KEYMILE Software Produkte 7.2 Sinn und Zweck Es besteht die Anforderung, dass diverse Properties aus dem IVM-EEPROM direkt zugänglich sind. Da im Kernel für den EEPROM Access der generische Treiber at24 verwendet werden muss [3, Kapitel 6], ist es über das sysfs nicht direkt möglich, beispielsweise den Hardware-Key aus dem EEPROM abzufragen. Eine Anforderung sieht vor, direkten Zugriff auf IVM-EEPROM-Properties zu ermöglichen. Da der Kernel den generischen at24-treiber für das IVM verwendet, werden in einer Software-Komponente die Zugriffsmethoden in Form eines APIs bereit gestellt. 7.3 Repository Die Applikationssoftware wird mit Subversion verwaltet. Entwickelt wird auf dem Trunk, versioniert wird auf Tags. SVN Pfad der Komponente: http://srv-esw-users/esw_users/ trunk/users/nherzc/components/linuxi2c tags/users/nherzc/components/linuxi2c/x.yy.zz Eine ausführliche Dokumentation von Subversion ist in deutscher Sprache als Openbook verfügbar [12]. 7.4 Struktur der Komponente Die Abbildung 13 zeigt den Aufbau der erstellten Komponente. Jeder farbige Kasten repräsentiert eine eigene Klasse. Das API wird in der Service Klasse zur Verfügung gestellt. 10.09.2009 Seite 14 Christian Herzig

Abbildung 13: Schichten der linuxi2c Komponente 7.5 Design Die Komponente umfasst mehr als nur ein API. Mittels Stimuli, einem Command Line Interface basierten Kommunikationskanal über das serielle Terminal oder Telnet, können einzelne Funktionen der Komponente ausgeführt werden. Die Abbildung 14 zeigt das Klassendiagramm der Stimuli Struktur. Alle Klassen erben von Stimuli_Commands. DumpIvmEeprom erbt von DumpEeprom, da das IVM-EEPROM ein spezialisiertes EEPROM ist. class Stimuli Stimuli_Command DumpEeprom ShowIv mhwkey ExportEeprom ShowBoardId EraseEeprom ListAllEeproms # printcontent() : void + doaction() : void + doaction() : void + doaction() : void + doaction() : void + doaction() : void + doaction() : void DumpIv meeprom GetTemp SetThreshold GetThreshold ListAllThresholds ListAllTemps - printtable() : void + doaction() : void + doaction() : void + doaction() : void + doaction() : void + doaction() : void + doaction() : void Abbildung 14: Klassendiagramm der Stimuli Struktur 10.09.2009 Seite 15 Christian Herzig