diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration | 13 | ||||
| -rw-r--r-- | Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget | 13 | ||||
| -rw-r--r-- | Documentation/ABI/testing/sysfs-socinfo | 16 | ||||
| -rw-r--r-- | Documentation/DocBook/Makefile | 7 | ||||
| -rw-r--r-- | Documentation/DocBook/device-drivers.tmpl | 17 | ||||
| -rw-r--r-- | Documentation/DocBook/gpio.tmpl | 112 | ||||
| -rw-r--r-- | Documentation/DocBook/i2c.tmpl | 116 | ||||
| -rw-r--r-- | Documentation/DocBook/prcmu-fw-api.tmpl | 109 | ||||
| -rw-r--r-- | Documentation/DocBook/stmpe.tmpl | 115 | ||||
| -rwxr-xr-x[-rw-r--r--] | Documentation/DocBook/stylesheet.xsl | 28 | ||||
| -rw-r--r-- | Documentation/DocBook/ux500_usb.tmpl | 151 | ||||
| -rw-r--r-- | Documentation/ioctl/ioctl-number.txt | 1 | ||||
| -rw-r--r-- | Documentation/trace/stm-trace.txt | 193 |
13 files changed, 880 insertions, 11 deletions
diff --git a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration new file mode 100644 index 00000000000..ae217d4a3a6 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration @@ -0,0 +1,13 @@ +What: Attribute for calibrating ST-Ericsson AB8500 Real Time Clock +Date: Oct 2011 +KernelVersion: 3.0 +Contact: Mark Godfrey <mark.godfrey@stericsson.com> +Description: The rtc_calibration attribute allows the userspace to + calibrate the AB8500.s 32KHz Real Time Clock. + Every 60 seconds the AB8500 will correct the RTC's value + by adding to it the value of this attribute. + The range of the attribute is -127 to +127 in units of + 30.5 micro-seconds (half-parts-per-million of the 32KHz clock) +Users: The /vendor/st-ericsson/base_utilities/core/rtc_calibration + daemon uses this interface. + diff --git a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget index d548eaac230..3bf505e7227 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget +++ b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget @@ -19,3 +19,16 @@ Description: Possible values are: 1 -> ignore the FUA flag 0 -> obey the FUA flag + +What: /sys/devices/platform/_UDC_/gadget/host_request +Date: December 2010 +Contact: Pavan Kondeti <pkondeti@...> +Description: + OTG 2.0 compliant host keeps polling OTG2.0 peripheral + for host role. Set host_request flag, which tells host + to give up the host role to peripheral. + + 1 -> host role is requested + 0 -> no effect (automatically cleared upon reset/disconnect) + + (_UDC_ is the name of the USB Device Controller driver) diff --git a/Documentation/ABI/testing/sysfs-socinfo b/Documentation/ABI/testing/sysfs-socinfo new file mode 100644 index 00000000000..afd9da2fa76 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-socinfo @@ -0,0 +1,16 @@ +What: /sys/socinfo +Date: March 2011 +contact: Maxime Coquelin <maxime.coquelin-nonst@stericsson.com> +Description: + The /sys/socinfo directory contains information about the + System-on-Chip. It is only available if platform implements it. + This directory contains two kind of attributes : + - common attributes: + * machine: the name of the machine. + * family: the family name of the SoC + - SoC-specific attributes: The SoC vendor can declare attributes + to export some strings to user-space, like the serial-number for + example. + +Users: + User-space applications which needs these kind of attributes. diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 66725a3d30d..80c42603ff2 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -14,7 +14,12 @@ DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ 80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ - tracepoint.xml drm.xml media_api.xml + tracepoint.xml drm.xml media_api.xml \ + i2s.xml msp.xml shrm.xml stmpe.xml touchp.xml \ + tc_keypad.xml prcmu-fw-api.xml cg2900_fm_radio.xml \ + synaptics_rmi4_touchp.xml db5500_keypad.xml \ + u5500_LogicalMailbox.xml cg2900.xml \ + lsm303dlh.xml ste_ff_vibra.xml ux500_usb.xml include $(srctree)/Documentation/DocBook/media/Makefile diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index b638e50cf8f..5f70f734e8b 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -437,4 +437,21 @@ X!Idrivers/video/console/fonts.c !Edrivers/i2c/i2c-core.c </chapter> + <chapter id="hsi"> + <title>High Speed Synchronous Serial Interface (HSI)</title> + + <para> + High Speed Synchronous Serial Interface (HSI) is a + serial interface mainly used for connecting application + engines (APE) with cellular modem engines (CMT) in cellular + handsets. + + HSI provides multiplexing for up to 16 logical channels, + low-latency and full duplex communication. + </para> + +!Iinclude/linux/hsi/hsi.h +!Edrivers/hsi/hsi.c + </chapter> + </book> diff --git a/Documentation/DocBook/gpio.tmpl b/Documentation/DocBook/gpio.tmpl new file mode 100644 index 00000000000..b69c2770210 --- /dev/null +++ b/Documentation/DocBook/gpio.tmpl @@ -0,0 +1,112 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> + +<book id="GPIO"> + <bookinfo> + <title>GPIO1B</title> + + <authorgroup> + <author> + <firstname>Alessandro</firstname> + <surname>Rubini</surname> + <affiliation> + <address> + <email>rubini@unipv.it</email> + </address> + </affiliation> + </author> + <author> + <firstname>Prafulla</firstname> + <surname>WADASKAR</surname> + <affiliation> + <address> + <email>prafulla.wadaskar@st.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2008-2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <!-- Do NOT remove the legal notice below --> + + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + </para> + + <para> + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + </para> + + <para> + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the source + distribution of Linux. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + <chapter id="intro"> + <title>Introduction</title> + <para> + This Documentation describes the API's provided by the GPIO controller Driver. + </para> + <para> + Only the API specific to the Ux500 platform is listed here. For the generic GPIO + API, see <filename>Documentation/gpio.txt</filename> in the kernel source tree. + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + <variablelist> + <varlistentry> + <term>None</term> + <listitem> + <para> + None. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </chapter> + + <chapter id="pubfunctions"> + <title> Public Interface </title> + <para> + This Section lists the API's provided by the GPIO controller driver to client drivers. + </para> + <para> + Only the API specific to the Ux500 platform is listed here. For the generic GPIO + API, see <filename>Documentation/gpio.txt</filename> in the kernel source tree. + </para> +!Earch/arm/plat-nomadik/gpio.c + </chapter> +</book> diff --git a/Documentation/DocBook/i2c.tmpl b/Documentation/DocBook/i2c.tmpl new file mode 100644 index 00000000000..8a4cb49204e --- /dev/null +++ b/Documentation/DocBook/i2c.tmpl @@ -0,0 +1,116 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> + +<book id="I2C"> + <bookinfo> + <title>I2C</title> + + <authorgroup> + <author> + <firstname>Srinidhi</firstname> + <surname>Kasagar</surname> + <affiliation> + <address> + <email>srinidhi.kasagar@stericsson.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Sachin</firstname> + <surname>Verma</surname> + <affiliation> + <address> + <email>sachin.verma@st.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2009-2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <!-- Do NOT remove the legal notice below --> + + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + </para> + + <para> + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + </para> + + <para> + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the source + distribution of Linux. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + <chapter id="intro"> + <title>Introduction</title> + <para> + This Documentation describes the API's provided by the I2C controller Driver. + Since this driver registers the transferfunction with kernel framework, there + are only private functions in this I2C bus driver. This driver currently + works only in master mode and does 7 bit adderssing only. There is no support + for 10 bit addressing. The driver currently supports standard mode (100KHz) + and Fast mode (400KHz) operation. + </para> + </chapter> + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + <variablelist> + <varlistentry> + <term>None</term> + <listitem> + <para> + None. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + Not Applicable + </para> + </chapter> + + <chapter id="private"> + <title>Private Functions</title> + <para> + This Section lists the functions used internally by the I2C controller driver. + </para> +!Idrivers/i2c/busses/i2c-nomadik.c + </chapter> + +</book> diff --git a/Documentation/DocBook/prcmu-fw-api.tmpl b/Documentation/DocBook/prcmu-fw-api.tmpl new file mode 100644 index 00000000000..445a277933c --- /dev/null +++ b/Documentation/DocBook/prcmu-fw-api.tmpl @@ -0,0 +1,109 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> + +<book id="STw4500"> + <bookinfo> + <title>PRCMU Driver</title> + + <authorgroup> + <author> + <firstname>Sudeep Karkada</firstname> + <surname>Nagesha</surname> + <affiliation> + <address> + <email>sudeepkarkada.nagesha@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2009-2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <!-- Do NOT remove the legal notice below --> + + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later + version. + </para> + + <para> + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + </para> + + <para> + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the source + distribution of Linux. + </para> + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + This documentation describes the API provided by the PRCMU firmware interface driver. + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + <variablelist> + <varlistentry> + <term>None</term> + <listitem> + <para> + None. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </chapter> + + <chapter id="enum"> + <title>Enumerations</title> + <para> + This chapter contains the autogenerated documentation of the structures + and enumerations which are used in the PRCMU firmware interface driver. + It is also required by the client drivers. + </para> +!Iinclude/linux/mfd/dbx500-prcmu.h + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + This chapter contains the autogenerated documentation of the kernel + API functions which are exported to the client drivers. + </para> +!Edrivers/mfd/db8500-prcmu.c + </chapter> + + + </book> diff --git a/Documentation/DocBook/stmpe.tmpl b/Documentation/DocBook/stmpe.tmpl new file mode 100644 index 00000000000..9e64a00f6b3 --- /dev/null +++ b/Documentation/DocBook/stmpe.tmpl @@ -0,0 +1,115 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> + +<book id="STMPE MFD devices"> + <bookinfo> + <title>STMPE IO-Port Expander guide</title> + + <authorgroup> + <author> + <firstname>Rabin</firstname> + <surname>Vincent</surname> + <affiliation> + <address> + <email>rabin.vincent@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2010</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Linux standard functions</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + </para> + + <para> + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + </para> + + <para> + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the source + distribution of Linux. + </para> + + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + This documentation describes the driver for STMicroelectronics + STMPExxxx port expander devices. + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <para> + <variablelist> + <varlistentry> + <term>None.</term> + <listitem> + <para> + None. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </chapter> + + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + List of public interfaces in stmpe driver + </para> +!Edrivers/mfd/stmpe.c + </chapter> + + <chapter id="private"> + <title>Private Functions</title> + <para> + STMPE Keypad driver + STMPE GPIO driver + </para> + <section id="stmpe-keypad.c"> + <title>stmpe-keypad.c</title> +!Idrivers/input/keyboard/stmpe-keypad.c + </section> + </chapter> + + <chapter id="Other"> + <title>Other Data Structures</title> + <para> + This Section lists some of the Data structure used by the stmpe driver and client drivers. + </para> +!Iinclude/linux/mfd/stmpe.h +!Idrivers/mfd/stmpe.h +</chapter> +</book> diff --git a/Documentation/DocBook/stylesheet.xsl b/Documentation/DocBook/stylesheet.xsl index 85b25275196..b2769ce5c8f 100644..100755 --- a/Documentation/DocBook/stylesheet.xsl +++ b/Documentation/DocBook/stylesheet.xsl @@ -1,10 +1,18 @@ -<?xml version="1.0" encoding="UTF-8"?> -<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0"> -<param name="chunk.quietly">1</param> -<param name="funcsynopsis.style">ansi</param> -<param name="funcsynopsis.tabular.threshold">80</param> -<param name="callout.graphics">0</param> -<!-- <param name="paper.type">A4</param> --> -<param name="generate.section.toc.level">2</param> -<param name="use.id.as.filename">1</param> -</stylesheet> +<?xml version='1.0'?> +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns:fo="http://www.w3.org/1999/XSL/Format" + version="1.0"> + <xsl:param name="use.id.as.filename" select="'1'"/> + <xsl:param name="admon.graphics" select="'1'"/> + <xsl:param name="admon.graphics.path"></xsl:param> + <xsl:param name="chunk.section.depth" select="2"></xsl:param> + <xsl:param name="chunk.quietly">1</xsl:param> + <xsl:param name="html.stylesheet" + select="'style.css'"/> + <xsl:param name="section.autolabel" select="1"/> + <xsl:param name="table.section.depth" select="1"/> + <xsl:param name="toc.section.depth" select="5"/> + <xsl:template name="user.header.content"> + <link href="../style.css" title="walsh" rel="stylesheet" type="text/css"/> + </xsl:template> +</xsl:stylesheet>
\ No newline at end of file diff --git a/Documentation/DocBook/ux500_usb.tmpl b/Documentation/DocBook/ux500_usb.tmpl new file mode 100644 index 00000000000..71b744386d4 --- /dev/null +++ b/Documentation/DocBook/ux500_usb.tmpl @@ -0,0 +1,151 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> + +<book id="USB-FUNCTION-Guide"> + <bookinfo> + <title>USB Driver Function guide</title> + + <authorgroup> + <author> + <firstname>Praveena</firstname> + <surname>Nadahally</surname> + <affiliation> + <address> + <email>praveen.nadahally@stericsson.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Rajaram</firstname> + <surname>Ragupathy</surname> + <affiliation> + <address> + <email>ragupathy.rajaram@stericsson.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>SakethRam</firstname> + <surname>Bommisetti</surname> + <affiliation> + <address> + <email>sakethram.bommisetti@stericsson.com</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2011</year> + <holder>ST-Ericsson</holder> + </copyright> + + <subjectset> + <subject> + <subjectterm>Connectivity</subjectterm> + </subject> + </subjectset> + + <legalnotice> + <para> + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + </para> + + <para> + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + </para> + + <para> + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + </para> + + <para> + For more details see the file COPYING in the source + distribution of Linux. + </para> + + </legalnotice> + </bookinfo> + +<toc></toc> + + <chapter id="intro"> + <title>Introduction</title> + <para> + This documentation describes ST-Ericsson's adaptation on USB external DMA and communication between Mentor USB IP controller and the USB + transreceiver + </para> + </chapter> + + <chapter id="concepts"> + <title>Concepts</title> + <!-- Do NOT change the chapter id or title! --> + <para> + In ST-Ericsson's USB driver, the open source linux gadget stack and Mentor IP USB 2.0 driver is used. Since the USB Transceiver and Mentor USB IP controller are on different hardware, API's are defined for the communication between them. These API's are available in ux500.c file. + The ST-Ericsson's USB driver doesn't have the internal DMA dedicated for USB. So, the external system DMA is used. The integration of external DMA with the mentor chip is available in ux500_dma.c file. + Changes have been made in the musb_core.c file where endpoints are configured as per the platform and also integrated DMA specific chnages in the musb_gadget.c file. + <!-- TODO: A brief introduction about the concepts + which are introduced by the driver. + Remove this chapter completely if there are no + special concepts introduced by this driver. + Do NOT change the chapter id or title! --> + <!-- TODO: This guideline for this chapter may be extended + during the user-guide guidelines drop. --> + </para> + </chapter> + + <chapter id="bugs"> + <title>Known Bugs And Assumptions</title> + <!-- Do NOT change the chapter id or title! --> + <para> + <variablelist> + + <varlistentry> + <term>None.</term> + <listitem> + <para> + </para> + </listitem> + </varlistentry> + + </variablelist> + + </para> + </chapter> + <chapter id="pubfunctions"> + <title>Public Functions Provided</title> + <para> + The musb driver doesn't export any functions. + </para> + </chapter> + <chapter id="intfunctions"> + <title>Internal Functions Provided</title> + <para> + List of internal functions + </para> + <!-- Do NOT change the chapter id or title! --> + <!-- TODO: Replace with link to appropriate headerfile(s), + source file(s), or both. One per row, ensure the + exclamation mark is on the first column! If no + appropriate header or source file exist describing a public interface, + replace the inclusion with a paragraph containing the text + "Not Applicable"--> + <section id="ux500_dma.c"> + <title>ux500_dma.c</title> +!Idrivers/usb/musb/ux500_dma.c + </section> + <section id="ux500.c"> + <title>ux500.c</title> +!Idrivers/usb/musb/ux500.c + </section> +</chapter> +</book> diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 54078ed96b3..af76fdef604 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -223,6 +223,7 @@ Code Seq#(hex) Include File Comments 'j' 00-3F linux/joystick.h 'k' 00-0F linux/spi/spidev.h conflict! 'k' 00-05 video/kyro.h conflict! +'k' 10-17 linux/hsi/hsi_char.h HSI character device 'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system <http://web.archive.org/web/*/http://mikonos.dia.unisa.it/tcfs> 'l' 40-7F linux/udf_fs_i.h in development: diff --git a/Documentation/trace/stm-trace.txt b/Documentation/trace/stm-trace.txt new file mode 100644 index 00000000000..cd73c2b87b7 --- /dev/null +++ b/Documentation/trace/stm-trace.txt @@ -0,0 +1,193 @@ + MIPI System Trace Module driver + =============================== + +Copyright (C) ST-Ericsson SA 2011 + Authors: Pierre Peiffer <pierre dot peiffer at stericsson dot com> + Philippe Langlais <philippe dot langlais at linaro dot org> + License: The GNU Free Documentation License, Version 1.2 + (dual licensed under the GPL v2) + +Hardware overview +================= + This hardware collects and provides simple tracepoints, + so a system processor (in our case the main ARM CPU, + or some small CPUs and DSPs) can write some data, + up to 8 bytes, into a register and out comes a log entry + with a time stamp (20ns resolution) on one of 256 channels. Also + hardware tracepoints are supported. + + This module external interface is a pad on the chip + which complies to the MIPI System Trace Protocol v1.0 + (see http://www.mipi.org/specifications/debug) + and the actual trace output can be read by an + electronic probe, not by software so it cannot be intercepted by + the CPU and reach Linux userspace. + + Bandwidth depends on number of lines & bus frequency (for example on ux500 + SoC 4 lines at max 100MHz eg max 400Mbit/s shared between 7 cores). + Transmit FIFO size: 256 samples up to 8 bytes. + On ux500 platform there is 2 contiguous STM blocks (eg 512 channels) + +Software Overview +================= + Write atomicity and write order on STM trace channels is ensured by the fact + we try to allocate one channel by execution thread (no concurrent access). + There is 2 modes one lossless but intrusive aka Software mode and + another lossy mode less intrusive aka Hardware mode, by default + all sources are configured in Hardware mode and enabled. + The end of data packet is marked by a time stamp on latest byte(s) only. + +Kernel API +---------- + Configuration functions: + output trace clock frequency, trace mode, output port configuration + and enable/disable STM trace sources + Expose a debugfs interface too for STM trace control + + Alloc/free STM trace channel functions + + Set of low level atomic trace functions for 1, 2, 4 or 8 bytes + with & w/o time stamp + + Higher level lockless trace functions: + stm_trace_buffer: + allocate a channel in 128 highest channels available + output the trace buffer with arbitrary length + (latest byte(s) automatically time stamped) then free the channel + stm_trace_buffer_onchannel: + use given channel to output the trace buffer + with arbitrary length (latest byte(s) automatically time stamped) + + File IO output console like interface (open, close, write) + + See <trace/stm.h> & drivers/misc/stm.c for more detail + +debugfs API +----------- +clockdiv: + This is used to set or display the current clock divisor + that is configured + +connection: + This is used to set or display the current output connector + that is configured (common values, 0 not connected, 1 for default + connection, 3 on Ux500 for APE MIPI34 connection) + +free_channels: + This is used to display the total number of free channels + +masters_enable: + This sets or displays whether the STM trace sources + are activated. Each bits represent the state of corresponding source: + 0 for disable or 1 to enable it. + +masters_modes: + This sets or displays the STM trace sources modes. + Each bits represent the mode of corresponding source: + 0 for Sofware lossless mode or 1 for Hardware lossy mode. + +User API +-------- + IOCTLs or debugfs for controls + 2 levels API for tracing: + - Standard write function, in this case a channel is automatically + allocated at first write, after you can channel number + with IOCTL STM_GET_CHANNEL_NO + - mmap for direct access of all STM trace channels port plus + a set of IOCTLs for alloc/free channels, in this case you can + write your own lib to easiest its usage + +Examples of using the STM +========================= +First mount debugfs with: +mount -t debugfs none /sys/kernel/debug + +In a shell scipt +---------------- +It's as easy as: + echo "My trace point" > /dev/stm + +To avoid trace overflow, increase STM clock by decreasing the clockdiv with: + echo 1 >/sys/kernel/debug/stm/clockdiv # now use DIV2 instead of default DIV8 +If not enough you can disable some sources with: + echo YourEnableSources > /sys/kernel/debug/stm/masters_enable +If always not enough the ultime intrusive way is to change the sources mode +and set the corresponding sources in Software mode (set corresponding source +bit to 0) with: + echo YourModeSources > /sys/kernel/debug/stm/masters_modes + (be aware some source doesn't support Software mode => keep it in HW mode) + +NB: on Ux500 platform, first you have to configure STM output port to switch +APE tracing on MIPI34 connector with: + echo 3 > /sys/kernel/debug/stm/connection + +In C language +------------- + +The easy way more intrusive (with STM buffer recopy): + +#include <trace/stm.h> + +int fd, i; +char buf[1024]; // Try to align this buffer on 64 bits if possible + + fd = open("/dev/stm", O_WRONLY); + snprintf(buf, 1024, "STM0 Hello world\n"); + write(fd, buf, strlen(buf)); + ioctl(fd, STM_GET_CHANNEL_NO, &i); + snprintf(buf, 1024, "Use channel #%d\n", i); + write(fd, buf, strlen(buf)); + close(fd); + +NB: You can call open("/dev/stm", O_WRONLY) as many times as necessary +to allocate a different channel to avoid concurrency in your +multithreaded application. + +The more efficient way, use mmap'ed STM channels memory (to put in a lib): + +#include <trace/stm.h> + +int fd, i, c, l, maxChannels; +char buf[1024]; // Try to align this buffer on 64 bits if possible +volatile struct stm_channel *channels; // mmap'ed channels area + + fd = open("/dev/stm", O_RDWR); + ioctl(fd0, STM_GET_NB_MAX_CHANNELS, &maxChannels); + channels = (struct stm_channel *)mmap(0, maxChannels*sizeof(*channels), + PROT_WRITE, MAP_SHARED, fd, 0); + assert(channels != MAP_FAILED); + + if (!ioctl(fd, STM_GET_FREE_CHANNEL, &c)) { + l = snprintf(buf, 1024, "STM0 Hello world on channel #%d\n", c); + // lazy implementation you have to send buffer by 8 Bytes when possible + // and be sure you don't share this channel with others threads + for (i=0; i<l; i++) { + channels[c].stamp8 = buf[i]; + } + ioctl(fd, STM_RELEASE_CHANNEL, c); + } + munmap((void *)channels, maxChannels*sizeof(*channels)); + close(fd); + +Kernel Internal usages +====================== +Dynamically channels dedicated for the kernel are allocated +in the 128 highest ones + +Via menuconfig you can: +- Duplicate printk output on a STM dedicated channel (255) +- Have realtime ftrace output to a STM dedicated channel (254), + if corresponding TRACER is enabled +- Have realtime sched context switch & sched wakeup output on dedicated channels + (253, 252), if corresponding TRACER is enabled +- Have Stack Trace on dedicated channels (251) +- Duplicate trace_printk output on dedicated channels (250 & 249) + + +And in the future: +------------------ +- Use it in standard kernel tracing infrastucture, + possibilities: + - Insert other STM trace calls before trace ring buffer write + - Substitute time stamping & trace ring buffer by STM + |