Differences

This shows you the differences between two versions of the page.

--- en:x86:eapi_linux [2019/11/22 13:45] – [x86 COM Express® EAPI Linux] weinholdo
+++ en:x86:eapi_linux [2023/02/06 09:18] (current) – removed weinholdo
@@ Line 1: / Line 1: @@
-====== x86 COM Express® EAPI Linux ======
-<WRAP round info>Please note that the x86 COM Express® EAPI Linux package is only available on request: [[Support@tq-group.com?subject=[EAPI Request] Linux|Request EAPI]]</WRAP>
-\\
-===== Preface =====
-<WRAP round important 60%>
-The Linux drivers package **tqmx86-dist-1.3.tar.gz** is intended to be installed on TQ modules based on the COM Express® standard.
-</WRAP>
-<WRAP round info 60%>
-**Tested operating systems:**
-  * Ubuntu 14.04 (Trusty Tahr) i386
-  * Ubuntu 16.04 (XenialXerus) i386
-  * Ubuntu 16.04 (XenialXerus) x86_64
-</WRAP>
-\\
-===== Supported Features =====
-  * TQMx86 PLD:
-    * Board ID
-    * I2C (both “soft” and “hard” types of I2C controller)
-    * GPIO
-    * Watchdog
-  * HW Monitor:
-    * Built-in coretemp sensors
-    * NCT7802 voltage sensors: 3V3, RTC-bat, 5VSB, COMe-Input
-    * NCT7802 temperature sensors: CPU and on-module
-    * NCT7802 fans: CPU and system
-  * On-module EEPROM
-\\
-===== Installation and set up procedure=====
-  * Boot Ubuntu, unpack //tqmx86-dist-1.3.tar.gz// and deploy provided drivers, configs and examples to rootfs
-  * Install additional test and developer tools, drivers package and corresponding dependencies: <code>$ sudo apt-get install i2c-tools lm-sensors
-$ sudo apt-get install dkms linux-headers-$(uname -r)
-$ sudo dpkg -i tqmx86-drivers_1.3_{i386,amd64}.deb </code>
-  * Copy ''configs/sensors.tqmx'' from //tqmx86-dist-1.3.tar.gz// to ''/etc/sensors.d/''<code>$ cp configs/sensors.tqmx /etc/sensors.d/</code> <wrap info>**//Note://** this configuration file has been tested on TQMxE38x module. For other TQ COMExpress modules, a following change may be required to make CPU-Temp sensor functional:\\ **label <wrap hi>temp1</wrap> “CPUtemp”** should be changed to **label <wrap hi>temp5</wrap> “CPUtemp”**</wrap>
-  * Copy ''configs/tqmx86.conf'' from //tqmx86-dist-1.3.tar.gz// to ''/etc/modules-load.d/''<code>$ cp configs/tqmx86.conf /etc/modules-load.d/</code>
-  * Edit ''/etc/modprobe.d/blacklist.conf'': Comment out '**blacklist i2c_i801**'<code>$ nano /etc/modprobe.d/blacklist.conf</code>
-  * Edit ''/etc/default/grub'': Add '**acpi_enforce_resources=lax**' parameter to the '**GRUB_CMDLINE_LINUX_DEFAULT**' variable definition <code>$ nano /etc/default/grub</code>
-    ++++ Example | <code>GRUB_CMDLINE_LINUX_DEFAULT="quiet splash acpi_enforce_resources=lax"</code> ++++\\
-  * <code>$ update-grub</code>
-  * <code>$ reboot</code>
-\\
-  * <code>$ lsmod</code> Check that the following kernel modules/drivers have been automatically loaded: \\ <code>tqmx86
-tqmx86_wdt
-gpio_tqmx86
-at24
-nct7802
-i2c_i801
-i2c_machxo2 or i2c_wishbone </code> <wrap info>**//Note://** starting from version R01.02, the package also supports a Lattice Wishbone soft I2C controller which is present on some versions of TQMx86 boards. For such boards, all instances of "i2c-machxo2" should be replaced with "i2c-wishbone" throughout this document.</wrap>
-  * If some driver has not been loaded, manually load it with command ''modprobe''
-  ++++ Example | <code>$ sudo modprobe nct7802
-$ sudo modprobe i2ci801 </code> ++++\\
-  * Check that everything is configured properly, i.e. the following device special and sysfs files and directories are present: <code>/dev/watchdog
-/dev/watchdog0
-/sys/devices/platform/tqmx86/
-/sys/devices/platform/tqmx86/i2c-machxo2/ (or i2c-wishbone)
-/sys/devices/platform/tqmx86/tqmx86wdt/
-/sys/devices/platform/tqmx86/tqmx86gpio/
-/sys/devices/pci0000:00/0000:00:1f.*/i2c*/*002c/hwmon/hwmon*
-/sys/devices/platform/tqmx86/i2c*/i2c*/*0050/ </code>
-\\
-===== Evaluating functionality =====
-==== Board and System information ====
-To obtain board and system information, following commands can be used:
-  - **BOARD_MANUFACTURER:** <code>$ cat /sys/class/dmi/id/sys_vendor</code>
-  - **BOARD_NAME:** <code>$ cat /sys/devices/platform/tqmx86/board_id</code>
-  - **BOARD_HW_REVISION:** <code>$ cat /sys/devices/platform/tqmx86/board_version</code>
-  - **BOARD_BIOS_REVISION:** <code>$ cat /sys/class/dmi/id/bios_version</code>
-++++ Example |
-<code>$ cat /sys/class/dmi/id/sys_vendor
-TQ-Group
-$ cat /sys/devices/platform/tqmx86/board_id
-TQMxE38M
-$ cat /sys/devices/platform/tqmx86/board_version
-$ cat /sys/class/dmi/id/bios_version
-TQMxE38M.5.4.48.0028.12</code>++++\\
-==== Watchdog ====
-A standard Watchdog API is provided by the driver. Please refer to official documentation
-for further reference: \\ [[https://www.kernel.org/doc/Documentation/watchdog/watchdog-api.txt|https://www.kernel.org/doc/Documentation/watchdog/watchdog-api.txt]]
-  - An example test program (**wdtest**) makes use of this API provided in //examples// directory of the //tqmx86-dist-1.3.tar.gz// archive. It can be compiled with following command: <code>$ gcc wdtest.c -o wdtest</code>
-  - Normal usage for the program is to run as daemon which periodically "pings" watchdog: <code>sudo sh -c "./wdtest -p 20 &" </code> The above command pings watchdog every 20 seconds - this is short enough for the default timeout period of 32 sec. \\ <wrap important>**//WARNING://** once the watchdog is first accessed it is started and cannot be stopped by any means - it can only be restarted by **wdtest** or similar watchdog daemon program or just by writing a character into ///dev/watchdog// (///dev/watchdog0//) file.</wrap>
-  - The wdtest command can also print watchdog info and set timeout. Following sequence of commands can be used to get watchdog info: <code>$ ps ax | grep wdtest
-pts/8 S 0:00 ./wdtest -p 20
-$ sudo kill -9 1686 ;sudo ./wdtest i ;sudo sh -c "./wdtest -p 20 &"
-Options: 8080, Version: 0, Id: TQMx86 Watchdog
-Status: 0
-Timeout: 32 </code> The above command kills the running daemon, requests watchdog info and starts new daemon.
-  - The watchdog timeout can be changed in similar way: <code>$ ps ax |grep wdtest
-pts/8 S 0:00 ./wdtest -p 20
-$ sudo kill -9 1703; sudo ./wdtest -t 800
-$ sudo sh -c "./wdtest -p 500 &" </code> The timeout is set to 1024sec \\ <wrap info>**//Note://** delay between 'kill' and 'start' commands should be short not to allow watchdog to reset the board.</wrap>
-\\
-==== GPIO ====
-A standard GPIO API is provided by the driver. Please refer to official documentation for
-further reference: \\
-[[https://www.kernel.org/doc/Documentation/gpio/sysfs.txt|https://www.kernel.org/doc/Documentation/gpio/sysfs.txt]] \\
-\\
-GPIO functionality may be tested by a **gpio-test.sh** shell script provided in //examples// directory of the //tqmx86-dist-1.3.tar.gz// archive. The program requires root privileges to export a 'pin' (once) and to change the output value. With a single 'pin' argument the program reports pin status (direction and value). When the second argument is provided it changes state of (output) pin accordingly: <code>sudo ./gpio-test.sh 2
-Direction: out
-Value: 0
-$ sudo ./gpio-test.sh 5
-Direction: in
-Value: 1
-$ sudo ./gpio-test.sh 2 1
-$ ./gpio-test.sh 2
-Direction: out
-Value: 1 </code>
-<wrap info>**//Note://** GPIO[0:3] are hardwired as outputs and GPIO[4:7] as inputs. Direction cannot be changed.</wrap>
-\\
-\\
-==== I2C and EEPROM ====
-A standard I2C dev API is provided by the driver. Please refer to official documentation for further reference: \\ [[https://www.kernel.org/doc/Documentation/i2c/dev-interface|https://www.kernel.org/doc/Documentation/i2c/dev-interface]] \\
-\\
-Let's consider several examples how to access devices on I2C bus:
-\\
-  * A standard EEPROM driver is automatically loaded for the “on-module” EEPROM at address 0x50. This driver represents the EEPROM as a regular file which can be read/written (truncation is not possible). E.g. to read the whole EEPROM, a following command can be used (note the wildcards usage in the pathname): <code> $ sudo hexdump -C /sys/devices/platform/tqmx86/i2c-*/i2c-*/*-0050/eeprom
-00000000 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
-00000010 54 51 4d 78 45 33 38 4d 0a ff ff ff ff ff ff ff |TQMxE38M........|
-00000020 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
-*
-a0 ff a1 ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
-b0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
-*
-00001000 </code>
-\\
-  * A PCA9538 GPIO expander chip on <nowiki>MB-COME6-1</nowiki> and <nowiki>MB-COME10-1</nowiki> carrier board can be accessed using i2c-tools according to following algorithm:
-        * Determine the number of **i2c-machxo2** (or **i2c-wishbone**) bus: <code>$ i2cdetect l
-i2c-0   unknown       i915 gmbus ssc                  N/A
-i2c-1   unknown       i915 gmbus vga                  N/A
-i2c-2   unknown       i915 gmbus panel                N/A
-i2c-3   unknown       i915 gmbus dpc                  N/A
-i2c-4   unknown       i915 gmbus dpb                  N/A
-i2c-5   unknown       i915 gmbus dpd                  N/A
-i2c-6   unknown       DPDDCB                          N/A
-i2c-7   unknown       DPDDCC                          N/A
-i2c-8   unknown       i2c-machxo2                      N/A
-i2c-9   unknown       SMBus I801 adapter at 3000      N/A </code>  (According to the output above, it's 8.)
-        * Read all 8 GPIO ports of PCA9538 located on this I2C bus: <code>$ sudo i2cdump -r 0-3 8 0x70
-[part of the output skipped]
-1 2 3 4 5 6 7 8 9 a b c d e f     0123456789abcdef
-: 05 ff 00 ff </code> All pins are configured as input, pins 0 and 2 are pulled up to 3.3V.
-        * Configure pins 0-3 as outputs: <code>$ sudo i2cset 8 0x70 3 0xf0
-$ sudo i2cdump -r 0-3 8 0x70
-: 0f ff 00 f0 </code>
-        * Change output state for pins 0-3 (pins 4-7 not affected as they are inputs): <code>$ sudo i2cset 8 0x70 1 0x06
-$ sudo i2cdump -r 0-3 8 0x70
-: 06 06 00 f0 </code> <wrap tip>//**Note:**// setting pin 0 to output value 0 should turn on LED.</wrap>\\
-++++ Option: PCA9540 I/O multiplexer| A TQMx86 module may be installed into a customized carrier board where a PCA9534 GPIO expander is located behind PCA9540 I/O multiplexers. To enable channel 0 of the multiplexer, write 4 into the only register of the multiplexer chip. This can be done with **i2cdump** utility (in the examples below an I2C bus number is 0): <code>$ sudo i2cdump -r 4-4 0 0x70
-:           00 </code> The command "reads" "register 4" which in case of the PCA9540 chip means writing "4" (register "address") into the only register and reading back the register (previous content is returned by PCA9540). Now few more devices appear on the I2C bus: <code>$ sudo i2cdetect -r 0
-:          -- -- -- -- -- -- -- -- -- -- -- -- --
-: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-: 20 21 -- -- -- -- -- -- -- -- -- -- -- -- -- -- </code> The two devices at addresses 0x20 and 0x21 are I2C to GPIO expanders PCA9534 which are similar to PCA9538 mentioned at the beginning of this section. Please follow corresponding instructions above how to evaluate the functionality of these chips. To disable the multiplexer channel 0, run the following command: <code>$ sudo i2cdump -r 0-0 0 0x70
-:  04 </code> ++++
-\\
-  * Accessing EEPROM on carrier using **i2c-rw** program:
-        * Source code for **i2c-rw** test program is provided in //examples// directory of the //tqmx86-dist-1.3.tar.gz// archive. To compile it, execute following command: <code>$ gcc i2c-rw.c -o i2c-rw </code>
-        * Read EEPROM on i2c bus 8 at address 0x57 from offset 0, size 64: <code>$ sudo ./i2c-rw -s 8 0x57 0 0x40
-Time: 6344 usec
-: 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 ................
-: 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 ................
-: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................
-: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................ </code>
-        * Read EEPROM on i2c bus 8 at address 0x57 from offset 0xa00, size 512: <code>$ sudo ./i2c-rw -s 8 0x57 0xa00 0x200
-Time: 47233 usec
-a00: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................
-[skipped]
-af0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................
-b00: 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b ................
-b10: 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b 1b ................
-b20: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................
-[skipped]
-bf0: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................ </code>
-        * Write "Hello!" to the same EEPROM at offset 0x30: <code>$ echo -n "Hello!" |sudo ./i2c-rw -s -w 8 0x57 0x30
-Time: 978 usec
-$ sudo ./i2c-rw -s 8 0x57 0x20 0x20
-Time: 3400 usec
-: ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ................
-: 48 65 6c 6c 6f 21 ff ff ff ff ff ff ff ff ff ff Hello!.......... </code> <WRAP round info 60%>**//Note://** the program supports reading/writing up to 8K of data in a single request. However, i2c slave devices may impose different limits for a single operation. In particular:
-              * when reading EEPROM chip across its size boundary the read rolls over the chip memory size to the start;
-              * EEPROM chips installed on TQMx modules do not support writing across 32-byte 'page' boundary (the write wraps around the 'page' boundary).
-<wrap tip>Refer to datasheet for Microchip 24AA32A EEPROM for further details.</wrap>
-</WRAP>
-\\
-==== Hardware Monitor sensors ====
-A standard hwmon API is provided by the driver via sysfs. But a high-level wrapper/library libsensors can be used to access sensors as well. Please refer to official documentation for further reference: \\ [[https://www.kernel.org/doc/Documentation/hwmon/sysfs-interface|https://www.kernel.org/doc/Documentation/hwmon/sysfs-interface]] \\ \\ Standard Linux '**sensors**' command can be used to obtain NCT7802 and coretemp (MSR registers of CPU) hardware monitor data: <code>$ sensors
-coretemp-isa-0000
-Adapter: ISA adapter
-Core 0:        +30.0°C (high = +110.0°C, crit = +110.0°C)
-Core 1:        +30.0°C (high = +110.0°C, crit = +110.0°C)
-Core 2:        +31.0°C (high = +110.0°C, crit = +110.0°C)
-Core 3:        +31.0°C (high = +110.0°C, crit = +110.0°C)
-soc_dts0-virtual0
-Adapter: Virtual device
-temp1:        +29.0°C
-soc_dts1-virtual0
-Adapter: Virtual device
-temp1:        +30.0°C
-nct7802-i2c-9-2c
-Adapter: SMBus I801 adapter at 3000
-V3:          +3.37 V (min = +0.00 V, max = +4.09 V)
-RTCbat:       +3.02 V
-VSB:         +5.08 V (min = +0.00 V, max = +6.24 V)
-COMeinput:    +12.38 V (min = +0.00 V, max = +21.99 V)
-CPUfan:          0 RPM (min = 0 RPM)
-COMefan:      3936 RPM (min = 0 RPM)
-CPUtemp:      +30.2°C (low = +0.0°C, high = +85.0°C)
-                      (crit = +100.0°C)
-SYStemp:      +30.0°C (low = +0.0°C, high = +85.0°C)
-                      (crit = +100.0°C) </code>
-\\
-===== Known issues and limitations =====
-  * If Smart Battery is enabled in BIOS the i801 SMBus driver is not working anymore due to an ACPI handle conflict. If both has to be used the i801 SMBus driver has to be adapted.
-  * Due to BIOS incompatibility, ACPI SMBus driver (i2c-scmi) does not work and legacy i801 SMBus driver reports "resource conflict". To resolve the issue "**acpi_enforce_resources=lax**" should be added to the kernel command line.
-  * Setting I2C bus speed is possible only when the driver is loaded. Default speed is 100KHz. If 50 or 400KHz is desired, specify that in driver parameters: <code>$ sudo modprobe tqmx86 i2c_speed=50 </code> This parameter may be also added to file in <code>/etc/modprobe.d/</code> as:<code>options tqmx86 i2c_speed=50</code>
-  * The I2C driver supports operation in interrupt mode on modules with corresponding h/w support. IRQ number can be specified in tqmx86 driver parameters as "**i2c_irq=7**" ("**i2c_irq=0**" selects polling mode). However, this was not tested and may not be guaranteed.
-  * The I2C driver for Hardened I2C controller may work unstable when the I2C bus speed is set to 400 kHZ. Incorrect write/read operations may occur in this mode, e.g. when somedata is written to I2C EERPOM it may be written to wrong offset. It is recommended to use Soft I2C controller instead.
-  * When tqmx86.ko module is loaded, message about missing module signature is logged. This is caused by using DKMS based module package. Unfortunately DKMS is fundamentally incompatible with signed modules feature, because it builds modules on target system, where private key for module signing can't be available.
-  * Second stage and generation of interrupts are not supported by the watchdog driver as a rework of existing Linux interfaces is required to implement this functionality.