jtag:aspeed: add upstream community JTAG driver

Sources:
https://github.com/facebook/openbmc-linux/tree/dev-5.6

Signed-off-by: Daniel Goehring <dgoehrin@os.amperecomputing.com>

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]<linux/jtag.h>.
+
+		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]<linux/jtag.h>
+		for descriptions of all ioctls.
+
+Users:
+		userspace tools which wants to access to JTAG bus

Documentation/devicetree/bindings/jtag/aspeed-jtag.yaml

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: https://urldefense.proofpoint.com/v2/url?u=http-3A__devicetree.org_schemas_jtag_aspeed-2Djtag.yaml-23&d=DwIBAg&c=5VD0RTtNlTh3ycd41b3MUw&r=iYElT7HC77pRZ3byVvW8ng&m=vGWCsGcOo2XBzrFEoF2nIS4gWviJ18aq1W4UxkRbmXA&s=5LDPQjHKBcLkVCSOxFNx3oLtdKgpW5T1u56Km9Lch5s&e=
+$schema: https://urldefense.proofpoint.com/v2/url?u=http-3A__devicetree.org_meta-2Dschemas_core.yaml-23&d=DwIBAg&c=5VD0RTtNlTh3ycd41b3MUw&r=iYElT7HC77pRZ3byVvW8ng&m=vGWCsGcOo2XBzrFEoF2nIS4gWviJ18aq1W4UxkRbmXA&s=r89VV7bcxrO-vDJsqHLKtJVbs-nZVmROiBZlM8YHtiQ&e=
+
+title: Aspeed JTAG driver for ast2400 and ast2500 SoC
+
+description:
+  Driver adds support of Aspeed 2500/2400 series SOC JTAG master controller.
+  Driver implements the following jtag ops
+    freq_get
+    freq_set
+    status_get
+    status_set
+    xfer
+    mode_set
+    bitbang
+    enable
+    disable
+
+  It has been tested on Mellanox system with BMC equipped with
+  Aspeed 2520 SoC for programming CPLD devices.
+
+  It has also been tested on Intel system using Aspeed 25xx SoC
+  for JTAG communication.
+
+maintainers:
+  - Oleksandr Shamray <oleksandrs@mellanox.com>
+  - Jiri Pirko <jiri@mellanox.com>
+  - Ernesto Corona<ernesto.corona@intel.com>
+
+properties:
+  compatible:
+    oneOf:
+      - items:
+          - enum:
+              - aspeed,ast2400-jtag
+              - aspeed,ast2500-jtag
+
+
+  reg:
+    items:
+      - description: JTAG Master controller register range
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+
+examples:
+  - |
+    #include <dt-bindings/clock/aspeed-clock.h>
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+      jtag: jtag@1e6e4000 {
+          compatible = "aspeed,ast2500-jtag";
+          reg = <0x1e6e4000 0x1c>;
+          clocks = <&syscon ASPEED_CLK_APB>;
+          resets = <&syscon ASPEED_RESET_JTAG_MASTER>;
+          interrupts = <43>;
+      };
+
+...

Documentation/index.rst

@@ -111,6 +111,7 @@ needed).
    iio/index
    isdn/index
    infiniband/index
+   jtag/index
    leds/index
    netlabel/index
    networking/index

Documentation/jtag/index.rst

@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+Joint Test Action Group (JTAG)
+==============================
+
+.. toctree::
+   :maxdepth: 1
+
+   jtag-summary
+   jtagdev
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`

Documentation/jtag/jtag-summary.rst

@@ -0,0 +1,47 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================
+Linux kernel JTAG support
+====================================
+
+Introduction to JTAG
+====================
+
+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 -> JTAG core driver -> JTAG hardware specific driver
+	User: ioctl -> /dev/jtagX -> JTAG core driver -> JTAG hardware specific driver
+	User: close -> /dev/jatgX -> JTAG core driver -> JTAG hardware specific driver
+
+
+THANKS TO
+---------
+Contributors to Linux-JTAG discussions include (in alphabetical order,
+by last name):
+
+- Ernesto Corona
+- Jiri Pirko
+- Oleksandr Shamray
+- Steven Filary
+- Vadim Pasternak

Documentation/jtag/jtagdev.rst

@@ -0,0 +1,194 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================
+JTAG userspace 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/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_SIOCSTATE - Force JTAG state machine to go into a TAPC state
+	JTAG_SIOCFREQ - Set JTAG TCK frequency
+	JTAG_GIOCFREQ - Get JTAG TCK frequency
+	JTAG_IOCXFER - send/receive JTAG data Xfer
+	JTAG_GIOCSTATUS - get current JTAG TAP state
+	JTAG_SIOCMODE - set JTAG mode flags.
+	JTAG_IOCBITBANG - JTAG bitbang low level control.
+
+JTAG_SIOCFREQ
+~~~~~~~~~~~~~
+Set JTAG clock speed:
+::
+
+	unsigned int jtag_fd;
+	ioctl(jtag_fd, JTAG_SIOCFREQ, &frq);
+
+JTAG_GIOCFREQ
+~~~~~~~~~~~~~
+Get JTAG clock speed:
+::
+
+	unsigned int jtag_fd;
+	ioctl(jtag_fd, JTAG_GIOCFREQ, &frq);
+
+JTAG_SIOCSTATE
+~~~~~~~~~~~~~~
+Force JTAG state machine to go into a TAPC state
+::
+
+	struct jtag_end_tap_state {
+		__u8	reset;
+		__u8	endstate;
+		__u8	tck;
+	};
+
+reset: one of below options
+::
+
+	JTAG_NO_RESET - go through selected endstate from current state
+	JTAG_FORCE_RESET - go through TEST_LOGIC/RESET state before selected endstate
+
+endstate: any state listed in jtag_endstate enum
+::
+
+	enum jtag_endstate {
+		JTAG_STATE_TLRESET,
+		JTAG_STATE_IDLE,
+		JTAG_STATE_SELECTDR,
+		JTAG_STATE_CAPTUREDR,
+		JTAG_STATE_SHIFTDR,
+		JTAG_STATE_EXIT1DR,
+		JTAG_STATE_PAUSEDR,
+		JTAG_STATE_EXIT2DR,
+		JTAG_STATE_UPDATEDR,
+		JTAG_STATE_SELECTIR,
+		JTAG_STATE_CAPTUREIR,
+		JTAG_STATE_SHIFTIR,
+		JTAG_STATE_EXIT1IR,
+		JTAG_STATE_PAUSEIR,
+		JTAG_STATE_EXIT2IR,
+		JTAG_STATE_UPDATEIR
+	};
+
+tck: clock counter
+
+Example:
+::
+
+	struct jtag_end_tap_state end_state;
+
+	end_state.endstate = JTAG_STATE_IDLE;
+	end_state.reset = 0;
+	end_state.tck = data_p->tck;
+	usleep(25 * 1000);
+	ioctl(jtag_fd, JTAG_SIOCSTATE, &end_state);
+
+JTAG_GIOCSTATUS
+~~~~~~~~~~~~~~~
+Get JTAG TAPC current machine state
+::
+
+	unsigned int jtag_fd;
+	jtag_endstate endstate;
+	ioctl(jtag_fd, JTAG_GIOCSTATUS, &endstate);
+
+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_READ_XFER/JTAG_WRITE_XFER/JTAG_READ_WRITE_XFER
+
+length: xfer data length in bits
+
+tdio : xfer data array
+
+endstate: end state after transaction finish any of jtag_endstate enum
+
+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 if (is_write)
+		xfer.direction = JTAG_WRITE_XFER;
+	else
+		xfer.direction = JTAG_READ_WRITE_XFER;
+
+	ioctl(jtag_fd, JTAG_IOCXFER, &xfer);
+
+JTAG_SIOCMODE
+~~~~~~~~~~~~~
+If hardware driver can support different running modes you can change it.
+
+Example:
+::
+
+	struct jtag_mode mode;
+	mode.feature = JTAG_XFER_MODE;
+	mode.mode = JTAG_XFER_HW_MODE;
+	ioctl(jtag_fd, JTAG_SIOCMODE, &mode);
+
+JTAG_IOCBITBANG
+~~~~~~~~~~~~~~~
+JTAG Bitbang low level operation.
+
+Example:
+::
+
+	struct tck_bitbang bitbang
+	bitbang.tms = 1;
+	bitbang.tdi = 0;
+	ioctl(jtag_fd, JTAG_IOCBITBANG, &bitbang);
+	tdo = bitbang.tdo;
+
+
+THANKS TO
+---------
+Contributors to Linux-JTAG discussions include (in alphabetical order,
+by last name):
+
+- Ernesto Corona
+- Jiri Pirko
+- Oleksandr Shamray
+- Steven Filary
+- Vadim Pasternak

Documentation/userspace-api/ioctl/ioctl-number.rst

@@ -335,6 +335,8 @@ Code  Seq#    Include File                                           Comments
                                                                      <mailto:vgo@ratio.de>
 0xB1  00-1F                                                          PPPoX
                                                                      <mailto:mostrows@styx.uwaterloo.ca>
+0xB2  00-0F  linux/jtag.h                                            JTAG driver
+                                                                     <mailto:oleksandrs@mellanox.com>
 0xB3  00     linux/mmc/ioctl.h
 0xB4  00-0F  linux/gpio.h                                            <mailto:linux-gpio@vger.kernel.org>
 0xB5  00-0F  uapi/linux/rpmsg.h                                      <mailto:linux-remoteproc@vger.kernel.org>

MAINTAINERS

@@ -9297,6 +9297,17 @@ L:	linux-serial@vger.kernel.org
 S:	Orphan
 F:	drivers/tty/serial/jsm/
 
+JTAG SUBSYSTEM
+M:      Oleksandr Shamray <oleksandrs@mellanox.com>
+M:      Vadim Pasternak <vadimp@mellanox.com>
+M       Ernesto Corona <ernesto.corona@intel.com>
+S:      Maintained
+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 <clemens@ladisch.de>
 L:	linux-hwmon@vger.kernel.org