Received: by 2002:a25:4158:0:0:0:0:0 with SMTP id o85csp2418459yba; Mon, 22 Apr 2019 06:31:24 -0700 (PDT) X-Google-Smtp-Source: APXvYqw+Bj6/Wvswea9+jJDF1kU9LFFu1PZd8noff2vj+J7ke+b0oZXOAVCUq6raoudhKOV7+GvP X-Received: by 2002:a62:e10e:: with SMTP id q14mr2941985pfh.161.1555939884511; Mon, 22 Apr 2019 06:31:24 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1555939884; cv=none; d=google.com; s=arc-20160816; b=NTJDmRGquqctn5Jcn00rJH/kFOjckul5PQPNCkLZeLBzlRSzhrwl1UTr5/OJNoHLBP 67SsWQtIBgYM3jL0SAYXnkszHPVhktcLFvfV2SWsrl1tS4mRGqCA+k0/WyjQpRQAKRpB RuNVN29AadWgwCd17YpWqfi7BZRoQla/f9LBPlA+8URRXOGz8gWMqjLXWKyyXzwBVuf4 ThGcqpnmTxLznKe1kub1NkqjoEAOM1L/vB3TAHRI6V7PAbjdHgWNR6JWy1H0nsXfOwKz 8CnQVmj4XR6nqNkHxZSimYJUM69fhl5Sfmro6RZQk/S1Lmha0BjArYjjFd4LUOSzAha9 R6Cg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:content-transfer-encoding:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :dkim-signature; bh=saJ5wzpF8nHr9iYOCK91J3rutoZ4h+j622rnksjsDls=; b=DCL/ow0BEuKDOw+thKo7wQG0sHmIq7pMAuzO7JWpiMHsxhqhpv1onvVS0+STBxNLWU f7Xpr5lA/DEVCFZGoqHK2swVJY6koRUjR42bvF/8MVSHvN2fFA7D6jv3DJhKtk4fRmpI CXpJm0pXVHwF1jT4CN9r+aOQFcvurNFQd786/2j1S0Jo2opRngirDggc220088pqpaFO 84uGlEQRAoUXcw29680w/9ed5tNW2GbyfktrhX14hzcQ4To60+5FKcLVN44AVDN3tjV4 ccq7Efcv/F1TQ7EUtuqwVmjMFndCxzLZQCTqST7+GZ7bN1cPRXXZpvhGFPVYGGml6P69 uIPw== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=L9643lTX; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id g19si3130485pgk.532.2019.04.22.06.31.08; Mon, 22 Apr 2019 06:31:24 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=fail header.i=@infradead.org header.s=bombadil.20170209 header.b=L9643lTX; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727797AbfDVN2l (ORCPT + 99 others); Mon, 22 Apr 2019 09:28:41 -0400 Received: from bombadil.infradead.org ([198.137.202.133]:37712 "EHLO bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727549AbfDVN2V (ORCPT ); Mon, 22 Apr 2019 09:28:21 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=infradead.org; s=bombadil.20170209; h=Sender:Content-Transfer-Encoding: MIME-Version:References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help: List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=saJ5wzpF8nHr9iYOCK91J3rutoZ4h+j622rnksjsDls=; b=L9643lTXCqDJ54lJu+pUI1auVp oZnUF/rb1jEfCGhe5OFQ0situKmdTGKh6oEa2lxg/4La6jqhLCKKbTFtEYKkvkHbmD61eZBtSGryZ jZY0abP4R4nN/mZVs00sOnS2MUO2Hqf+9A66O5lQb9m+dGP5wSLr9jSeH4nXZtXYmtfF8voFriZJ/ MPZGUu6ECJj+G15E2raBjoSoGFWz9AVZ+WdBMbUaaR8skOWe1bGHam7RrXvwmmhkJl2zez/dp+UKi nM3p2I99Rq/vC4pbo/778IIIL6suMtCzo/uDIHemssyhQPGqGII6G6fYi/ZIcREtT+cAs++Clnosg ajV5Jg3g==; Received: from 179.176.125.229.dynamic.adsl.gvt.net.br ([179.176.125.229] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtpsa (Exim 4.90_1 #2 (Red Hat Linux)) id 1hIYzb-0005Ho-4X; Mon, 22 Apr 2019 13:28:19 +0000 Received: from mchehab by bombadil.infradead.org with local (Exim 4.92) (envelope-from ) id 1hIYzT-0005nC-Kt; Mon, 22 Apr 2019 10:28:11 -0300 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet Subject: [PATCH v2 46/79] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst Date: Mon, 22 Apr 2019 10:27:35 -0300 Message-Id: <2d67fa4c4031c7568ff43b282221fb2862d5a01d.1555938376.git.mchehab+samsung@kernel.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Convert this small file to ReST format and rename it. Most of the conversion were related to adjusting whitespaces in order for each section to be properly parsed. While this is not part of any book, mark it as :orphan:, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab --- Documentation/pti/pti_intel_mid.rst | 106 ++++++++++++++++++++++++++++ Documentation/pti/pti_intel_mid.txt | 99 -------------------------- 2 files changed, 106 insertions(+), 99 deletions(-) create mode 100644 Documentation/pti/pti_intel_mid.rst delete mode 100644 Documentation/pti/pti_intel_mid.txt diff --git a/Documentation/pti/pti_intel_mid.rst b/Documentation/pti/pti_intel_mid.rst new file mode 100644 index 000000000000..ea05725174cb --- /dev/null +++ b/Documentation/pti/pti_intel_mid.rst @@ -0,0 +1,106 @@ +:orphan: + +============= +Intel MID PTI +============= + +The Intel MID PTI project is HW implemented in Intel Atom +system-on-a-chip designs based on the Parallel Trace +Interface for MIPI P1149.7 cJTAG standard. The kernel solution +for this platform involves the following files:: + + ./include/linux/pti.h + ./drivers/.../n_tracesink.h + ./drivers/.../n_tracerouter.c + ./drivers/.../n_tracesink.c + ./drivers/.../pti.c + +pti.c is the driver that enables various debugging features +popular on platforms from certain mobile manufacturers. +n_tracerouter.c and n_tracesink.c allow extra system information to +be collected and routed to the pti driver, such as trace +debugging data from a modem. Although n_tracerouter +and n_tracesink are a part of the complete PTI solution, +these two line disciplines can work separately from +pti.c and route any data stream from one /dev/tty node +to another /dev/tty node via kernel-space. This provides +a stable, reliable connection that will not break unless +the user-space application shuts down (plus avoids +kernel->user->kernel context switch overheads of routing +data). + +An example debugging usage for this driver system: + + * Hook /dev/ttyPTI0 to syslogd. Opening this port will also start + a console device to further capture debugging messages to PTI. + * Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW. + This is where n_tracerouter and n_tracesink are used. + * Hook /dev/pti to a user-level debugging application for writing + to PTI HW. + * `Use mipi_` Kernel Driver API in other device drivers for + debugging to PTI by first requesting a PTI write address via + mipi_request_masterchannel(1). + +Below is example pseudo-code on how a 'privileged' application +can hook up n_tracerouter and n_tracesink to any tty on +a system. 'Privileged' means the application has enough +privileges to successfully manipulate the ldisc drivers +but is not just blindly executing as 'root'. Keep in mind +the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter +and n_tracesink line discpline drivers but is a generic +operation for a program to use a line discpline driver +on a tty port other than the default n_tty:: + + /////////// To hook up n_tracerouter and n_tracesink ///////// + + // Note that n_tracerouter depends on n_tracesink. + #include + #define ONE_TTY "/dev/ttyOne" + #define TWO_TTY "/dev/ttyTwo" + + // needed global to hand onto ldisc connection + static int g_fd_source = -1; + static int g_fd_sink = -1; + + // these two vars used to grab LDISC values from loaded ldisc drivers + // in OS. Look at /proc/tty/ldiscs to get the right numbers from + // the ldiscs loaded in the system. + int source_ldisc_num, sink_ldisc_num = -1; + int retval; + + g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W + g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W + + if (g_fd_source <= 0) || (g_fd_sink <= 0) { + // doubt you'll want to use these exact error lines of code + printf("Error on open(). errno: %d\n",errno); + return errno; + } + + retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num); + if (retval < 0) { + printf("Error on ioctl(). errno: %d\n", errno); + return errno; + } + + retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num); + if (retval < 0) { + printf("Error on ioctl(). errno: %d\n", errno); + return errno; + } + + /////////// To disconnect n_tracerouter and n_tracesink //////// + + // First make sure data through the ldiscs has stopped. + + // Second, disconnect ldiscs. This provides a + // little cleaner shutdown on tty stack. + sink_ldisc_num = 0; + source_ldisc_num = 0; + ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num); + ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num); + + // Three, program closes connection, and cleanup: + close(g_fd_uart); + close(g_fd_gadget); + g_fd_uart = g_fd_gadget = NULL; diff --git a/Documentation/pti/pti_intel_mid.txt b/Documentation/pti/pti_intel_mid.txt deleted file mode 100644 index e7a5b6d1f7a9..000000000000 --- a/Documentation/pti/pti_intel_mid.txt +++ /dev/null @@ -1,99 +0,0 @@ -The Intel MID PTI project is HW implemented in Intel Atom -system-on-a-chip designs based on the Parallel Trace -Interface for MIPI P1149.7 cJTAG standard. The kernel solution -for this platform involves the following files: - -./include/linux/pti.h -./drivers/.../n_tracesink.h -./drivers/.../n_tracerouter.c -./drivers/.../n_tracesink.c -./drivers/.../pti.c - -pti.c is the driver that enables various debugging features -popular on platforms from certain mobile manufacturers. -n_tracerouter.c and n_tracesink.c allow extra system information to -be collected and routed to the pti driver, such as trace -debugging data from a modem. Although n_tracerouter -and n_tracesink are a part of the complete PTI solution, -these two line disciplines can work separately from -pti.c and route any data stream from one /dev/tty node -to another /dev/tty node via kernel-space. This provides -a stable, reliable connection that will not break unless -the user-space application shuts down (plus avoids -kernel->user->kernel context switch overheads of routing -data). - -An example debugging usage for this driver system: - *Hook /dev/ttyPTI0 to syslogd. Opening this port will also start - a console device to further capture debugging messages to PTI. - *Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW. - This is where n_tracerouter and n_tracesink are used. - *Hook /dev/pti to a user-level debugging application for writing - to PTI HW. - *Use mipi_* Kernel Driver API in other device drivers for - debugging to PTI by first requesting a PTI write address via - mipi_request_masterchannel(1). - -Below is example pseudo-code on how a 'privileged' application -can hook up n_tracerouter and n_tracesink to any tty on -a system. 'Privileged' means the application has enough -privileges to successfully manipulate the ldisc drivers -but is not just blindly executing as 'root'. Keep in mind -the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter -and n_tracesink line discpline drivers but is a generic -operation for a program to use a line discpline driver -on a tty port other than the default n_tty. - -/////////// To hook up n_tracerouter and n_tracesink ///////// - -// Note that n_tracerouter depends on n_tracesink. -#include -#define ONE_TTY "/dev/ttyOne" -#define TWO_TTY "/dev/ttyTwo" - -// needed global to hand onto ldisc connection -static int g_fd_source = -1; -static int g_fd_sink = -1; - -// these two vars used to grab LDISC values from loaded ldisc drivers -// in OS. Look at /proc/tty/ldiscs to get the right numbers from -// the ldiscs loaded in the system. -int source_ldisc_num, sink_ldisc_num = -1; -int retval; - -g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W -g_fd_sink = open(TWO_TTY, O_RDWR); // must be R/W - -if (g_fd_source <= 0) || (g_fd_sink <= 0) { - // doubt you'll want to use these exact error lines of code - printf("Error on open(). errno: %d\n",errno); - return errno; -} - -retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num); -if (retval < 0) { - printf("Error on ioctl(). errno: %d\n", errno); - return errno; -} - -retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num); -if (retval < 0) { - printf("Error on ioctl(). errno: %d\n", errno); - return errno; -} - -/////////// To disconnect n_tracerouter and n_tracesink //////// - -// First make sure data through the ldiscs has stopped. - -// Second, disconnect ldiscs. This provides a -// little cleaner shutdown on tty stack. -sink_ldisc_num = 0; -source_ldisc_num = 0; -ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num); -ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num); - -// Three, program closes connection, and cleanup: -close(g_fd_uart); -close(g_fd_gadget); -g_fd_uart = g_fd_gadget = NULL; -- 2.20.1