Received: by 2002:ac0:a5a7:0:0:0:0:0 with SMTP id m36-v6csp723300imm; Fri, 13 Jul 2018 05:24:16 -0700 (PDT) X-Google-Smtp-Source: AAOMgpcNRRtM5Z+ESK12ewMvBUfENkR2Ob2ebwbt1laL7mQtbF/rK36mn+wTQ7UtHfTstTyiu5K7 X-Received: by 2002:a17:902:a508:: with SMTP id s8-v6mr6325271plq.223.1531484656153; Fri, 13 Jul 2018 05:24:16 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1531484656; cv=none; d=google.com; s=arc-20160816; b=0+eenj8rJDRID79skvgVpg8ZGrsC9i2zoc4nKzGAZcRp2mehUtBrCGjO41kbDgHfqU du3LGjnu4nee1xV8gqIbKvDpY/OnXi3WTU81OSFcx5ogCTxl+TdMFyNtCsIfImxpuHzG H9LW6z3arzCpZ/kvKuCnf4GqiW4J07T7mEB2ytzGmjxqGagIHLQtYZ+YnjQQDqE0kXbK rAoRlZQ832cYXgDcWcHeATnMPeQHdx33FcZX8XeRAeMYxevp67PMiGwel+BELn47XINo ETmwQxIGcuBn8vpSAnWls+2JhW1K8u+CML5Xzo1aNo5P49vqIM3SA1Iuv1av5EN9NW0+ TVUQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:message-id:date :subject:cc:to:from:arc-authentication-results; bh=NqqcxjTJG+p1vZiXUQy7gu6du5NtXyd1YRBxuQvv8Lc=; b=lpSwDsfSqGsX/4yGvdV9td8wQmuWCDZS58xLgYbwJCgIjGr9+OzQPKphUIpkFHSNf2 chWoFVWnt6xsDVQXF+Sd7m87H2MOjgEx80vuWcaH3OFWShr1YZs31+Pgwko/Zt6/lEPl tWXulb9EaLrySGJY1jKopvivWfFjDCLN7GydrpMkx1AReHE8gLZ7WgEt2wn4vvy6qyJ3 /UkeOufQMB+Be6lAY7tJnGEc7mIpmyP6lDMI3SvWZ2v6OHrA06KfG7qeSwUkusUMA7O6 a15FuQR0cMVl/GgRn8eNBgv+TbQn81nlC8tW3nLwsuImPKMDU2JlwtFqxz1RzpemSd8F bALQ== ARC-Authentication-Results: i=1; mx.google.com; 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=mellanox.com Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id a5-v6si25921726pll.412.2018.07.13.05.24.01; Fri, 13 Jul 2018 05:24:16 -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; 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=mellanox.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1731589AbeGMMh3 (ORCPT + 99 others); Fri, 13 Jul 2018 08:37:29 -0400 Received: from mail-il-dmz.mellanox.com ([193.47.165.129]:51363 "EHLO mellanox.co.il" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1731383AbeGMMh2 (ORCPT ); Fri, 13 Jul 2018 08:37:28 -0400 Received: from Internal Mail-Server by MTLPINE1 (envelope-from oleksandrs@mellanox.com) with ESMTPS (AES256-SHA encrypted); 13 Jul 2018 15:25:56 +0300 Received: from r-vnc16.mtr.labs.mlnx (r-vnc16.mtr.labs.mlnx [10.208.0.16]) by labmailer.mlnx (8.13.8/8.13.8) with ESMTP id w6DCMtao022630; Fri, 13 Jul 2018 15:22:55 +0300 From: Oleksandr Shamray To: gregkh@linuxfoundation.org, arnd@arndb.de Cc: linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, devicetree@vger.kernel.org, openbmc@lists.ozlabs.org, joel@jms.id.au, jiri@resnulli.us, tklauser@distanz.ch, linux-serial@vger.kernel.org, vadimp@mellanox.com, system-sw-low-level@mellanox.com, robh+dt@kernel.org, openocd-devel-owner@lists.sourceforge.net, linux-api@vger.kernel.org, davem@davemloft.net, mchehab@kernel.org, Oleksandr Shamray Subject: [patch v27 4/4] Documentation: jtag: Add ABI documentation Date: Fri, 13 Jul 2018 15:22:54 +0300 Message-Id: <1531484574-9422-5-git-send-email-oleksandrs@mellanox.com> X-Mailer: git-send-email 1.7.1 In-Reply-To: <1531484574-9422-1-git-send-email-oleksandrs@mellanox.com> References: <1531484574-9422-1-git-send-email-oleksandrs@mellanox.com> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Added document that describe the ABI for JTAG class drivrer Signed-off-by: Oleksandr Shamray Acked-by: Arnd Bergmann --- v25->v26 Comments pointed by Randy Dunlap - fix spell in ABI documentation v24->v25 Comments pointed by Greg KH - Fixed documentation according to new open() behavior v23->v24 v22->v23 Comments pointed by Randy Dunlap - fix spell in ABI doccumentation v21->v22 Comments pointed by Randy Dunlap - fix spell in ABI doccumentation v20->v21 Comments pointed by Randy Dunlap - Fix JTAG dirver help in Kconfig v19->v20 Comments pointed by Randy Dunlap - Fix JTAG doccumentation v18->v19 Pavel Machek - Added JTAG doccumentation to Documentation/jtag v17->v18 v16->v17 v15->v16 v14->v15 v13->v14 v12->v13 v11->v12 Tobias Klauser Comments pointed by - rename /Documentation/ABI/testing/jatg-dev -> jtag-dev - Typo: s/interfase/interface v10->v11 v9->v10 Fixes added by Oleksandr: - change jtag-cdev to jtag-dev in documentation - update KernelVersion and Date in jtag-dev documentation; v8->v9 v7->v8 v6->v7 Comments pointed by Pavel Machek - Added jtag-cdev documentation to Documentation/ABI/testing folder --- Documentation/ABI/testing/jtag-dev | 23 ++++++++ Documentation/jtag/overview | 27 +++++++++ Documentation/jtag/transactions | 109 ++++++++++++++++++++++++++++++++++++ MAINTAINERS | 1 + 4 files changed, 160 insertions(+), 0 deletions(-) create mode 100644 Documentation/ABI/testing/jtag-dev create mode 100644 Documentation/jtag/overview create mode 100644 Documentation/jtag/transactions diff --git a/Documentation/ABI/testing/jtag-dev b/Documentation/ABI/testing/jtag-dev new file mode 100644 index 0000000..423baab --- /dev/null +++ b/Documentation/ABI/testing/jtag-dev @@ -0,0 +1,23 @@ +What: /dev/jtag[0-9]+ +Date: July 2018 +KernelVersion: 4.20 +Contact: oleksandrs@mellanox.com +Description: + The misc device files /dev/jtag* are the interface + between JTAG master interface and userspace. + + The ioctl(2)-based ABI is defined and documented in + [include/uapi]. + + The following file operations are supported: + + open(2) + Opens and allocates file descriptor. + + ioctl(2) + Initiate various actions. + See the inline documentation in [include/uapi] + for descriptions of all ioctls. + +Users: + userspace tools which wants to access to JTAG bus diff --git a/Documentation/jtag/overview b/Documentation/jtag/overview new file mode 100644 index 0000000..3c39052 --- /dev/null +++ b/Documentation/jtag/overview @@ -0,0 +1,27 @@ +Linux kernel JTAG support +========================= + +JTAG is an industry standard for verifying hardware. JTAG provides access to +many logic signals of a complex integrated circuit, including the device pins. + +A JTAG interface is a special interface added to a chip. +Depending on the version of JTAG, two, four, or five pins are added. + +The connector pins are: + TDI (Test Data In) + TDO (Test Data Out) + TCK (Test Clock) + TMS (Test Mode Select) + TRST (Test Reset) optional + +JTAG interface is designed to have two parts - basic core driver and +hardware specific driver. The basic driver introduces a general interface +which is not dependent of specific hardware. It provides communication +between user space and hardware specific driver. +Each JTAG device is represented as a char device from (jtag0, jtag1, ...). +Access to a JTAG device is performed through IOCTL calls. + +Call flow example: +User: open -> /dev/jatgX +User: ioctl -> /dev/jtagX -> JTAG core driver -> JTAG hardware specific driver +User: close -> /dev/jatgX diff --git a/Documentation/jtag/transactions b/Documentation/jtag/transactions new file mode 100644 index 0000000..e86fb73 --- /dev/null +++ b/Documentation/jtag/transactions @@ -0,0 +1,109 @@ +The JTAG API +============= + +JTAG master devices can be accessed through a character misc-device. +Each JTAG master interface can be accessed by using /dev/jtagN. + +JTAG system calls set: +- SIR (Scan Instruction Register, IEEE 1149.1 Instruction Register scan); +- SDR (Scan Data Register, IEEE 1149.1 Data Register scan); +- RUNTEST (Forces the IEEE 1149.1 bus to a run state for a specified +number of clocks. + +open(), close() +------- +open() opens JTAG device. + +Open/Close device: +- jtag_fd = open("/dev/jtag0", O_RDWR); +- close(jtag_fd); + +ioctl() +------- +All access operations to JTAG devices are performed through ioctl interface. +The IOCTL interface supports these requests: + JTAG_IOCRUNTEST - Force JTAG state machine to RUN_TEST/IDLE state + JTAG_SIOCFREQ - Set JTAG TCK frequency + JTAG_GIOCFREQ - Get JTAG TCK frequency + JTAG_IOCXFER - send JTAG data Xfer + JTAG_GIOCSTATUS - get current JTAG TAP status + JTAG_SIOCMODE - set JTAG mode flags. + +JTAG_SIOCFREQ, JTAG_GIOCFREQ +------ +Set/Get JTAG clock speed: + + unsigned int jtag_fd; + ioctl(jtag_fd, JTAG_SIOCFREQ, &frq); + ioctl(jtag_fd, JTAG_GIOCFREQ, &frq); + +JTAG_IOCRUNTEST +------ +Force JTAG state machine to RUN_TEST/IDLE state + +struct jtag_run_test_idle { + __u8 reset; + __u8 endstate; + __u8 tck; +}; + +reset: + JTAG_NO_RESET - run IDLE/PAUSE from current state + JTAG_FORCE_RESET - go through TEST_LOGIC/RESET state before IDLE/PAUSE +endstate: completion flag +tck: clock counter + +Example: + struct jtag_run_test_idle runtest; + + runtest.endstate = JTAG_STATE_IDLE; + runtest.reset = 0; + runtest.tck = data_p->tck; + usleep(25 * 1000); + ioctl(jtag_fd, JTAG_IOCRUNTEST, &runtest); + +JTAG_IOCXFER +------ +Send SDR/SIR transaction + +struct jtag_xfer { + __u8 type; + __u8 direction; + __u8 endstate; + __u8 padding; + __u32 length; + __u64 tdio; +}; + +type: transfer type - JTAG_SIR_XFER/JTAG_SDR_XFER +direction: xfer direction - JTAG_SIR_XFER/JTAG_SDR_XFER +length: xfer data length in bits +tdio : xfer data array +endstate: xfer end state after transaction finish + can be: JTAG_STATE_IDLE/JTAG_STATE_PAUSEIR/JTAG_STATE_PAUSEDR + +Example: + struct jtag_xfer xfer; + static char buf[64]; + static unsigned int buf_len = 0; + [...] + xfer.type = JTAG_SDR_XFER; + xfer.tdio = (__u64)buf; + xfer.length = buf_len; + xfer.endstate = JTAG_STATE_IDLE; + + if (is_read) + xfer.direction = JTAG_READ_XFER; + else + xfer.direction = JTAG_WRITE_XFER; + + ioctl(jtag_fd, JTAG_IOCXFER, &xfer); + +JTAG_SIOCMODE +------ +If hardware driver can support different running modes you can change it. + +Example: + unsigned int mode; + mode = JTAG_XFER_HW_MODE; + ioctl(jtag_fd, JTAG_SIOCMODE, &mode); diff --git a/MAINTAINERS b/MAINTAINERS index 169de71..0ae2cf8 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7698,6 +7698,7 @@ F: include/linux/jtag.h F: include/uapi/linux/jtag.h F: drivers/jtag/ F: Documentation/devicetree/bindings/jtag/ +F: Documentation/ABI/testing/jtag-dev K10TEMP HARDWARE MONITORING DRIVER M: Clemens Ladisch -- 1.7.1