path: root/meta-openbmc-mods/meta-common/recipes-kernel/linux/linux-aspeed/0055-Documentation-jtag-Add-ABI-documentation.patch

From c2d57900820475b50affd171f4dc423a278887ae Mon Sep 17 00:00:00 2001
From: "Corona, Ernesto" <ernesto.corona@intel.com>
Date: Wed, 10 Mar 2019 11:47:40 -0800
Subject: [PATCH v29 4/6] Documentation: jtag: Add ABI documentation

Added document that describe the ABI for JTAG class driver

Signed-off-by: Oleksandr Shamray <oleksandrs@mellanox.com>
Signed-off-by: Corona, Ernesto <ernesto.corona@intel.com>
Acked-by: Arnd Bergmann <arnd@arndb.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Jiri Pirko <jiri@mellanox.com>
Cc: Vadim Pasternak <vadimp@mellanox.com>
Cc: Steven A Filary <steven.a.filary@intel.com>
Cc: Bryan Hunt <bryan.hunt@intel.com>
---
v28->v29
Comments pointed by Steven Filary <steven.a.filary@intel.com>
- Expand bitbang function to accept multiples bitbang operations within a
  single JTAG_IOCBITBANG call. It will receive a buffer with TDI and TMS
  values and it is expected that driver fills TDO fields with its
  corresponding output value for every transaction.

v27->v28
Comments pointed by Steven Filary <steven.a.filary@intel.com>
- Replace JTAG_IOCRUNTEST with JTAG_SIOCSTATE adding support for all TAPC
   end states in SW mode using a lookup table to navigate across states.
- Add support for simultaneous READ/WRITE transfers(JTAG_READ_WRITE_XFER).
- Support for switching JTAG controller mode between slave and master
  mode.
- Setup JTAG controller mode to master only when the driver is opened,
  letting other HW to own the JTAG bus when it isn't in use.
- Include JTAG bit bang IOCTL for low level JTAG control usage
  (JTAG_IOCBITBANG).

v26->v27
v25->v26
Comments pointed by Randy Dunlap <rdunlap@infradead.org>
- fix spell in ABI documentation

v24->v25
Comments pointed by Greg KH <gregkh@linuxfoundation.org>
- Fixed documentation according to new open() behavior

v23->v24
v22->v23
Comments pointed by Randy Dunlap <rdunlap@infradead.org>
- fix spell in ABI doccumentation

v21->v22
Comments pointed by Randy Dunlap <rdunlap@infradead.org>
- fix spell in ABI doccumentation

v20->v21
Comments pointed by Randy Dunlap <rdunlap@infradead.org>
- Fix JTAG dirver help in Kconfig

v19->v20
Comments pointed by Randy Dunlap <rdunlap@infradead.org>
- Fix JTAG doccumentation

v18->v19
Pavel Machek <pavel@ucw.cz>
- Added JTAG doccumentation to Documentation/jtag

v17->v18
v16->v17
v15->v16
v14->v15
v13->v14
v12->v13
v11->v12 Tobias Klauser <tklauser@distanz.ch>
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 <pavel@ucw.cz>
- Added jtag-cdev documentation to Documentation/ABI/testing folder
---
 Documentation/ABI/testing/jtag-dev |  23 +++++++
 Documentation/jtag/overview        |  27 ++++++++
 Documentation/jtag/transactions    | 138 +++++++++++++++++++++++++++++++++++++
 3 files changed, 188 insertions(+)
 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]<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
diff --git a/Documentation/jtag/overview b/Documentation/jtag/overview
new file mode 100644
index 0000000..6a5ec33
--- /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 -> 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
diff --git a/Documentation/jtag/transactions b/Documentation/jtag/transactions
new file mode 100644
index 0000000..76fd0b1
--- /dev/null
+++ b/Documentation/jtag/transactions
@@ -0,0 +1,138 @@
+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_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, JTAG_GIOCFREQ
+------
+Set/Get JTAG clock speed:
+
+	unsigned int jtag_fd;
+	ioctl(jtag_fd, JTAG_SIOCFREQ, &frq);
+	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:
+	JTAG_NO_RESET - go through selected endstate from current state
+	JTAG_FORCE_RESET - go through TEST_LOGIC/RESET state before selected endstate
+endstate: completion flag
+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 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: xfer end state after transaction finish
+	   can be: any state listed in jtag_endstate struct
+
+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 bitbang_packet bitbang;
+	struct tck_bitbang bitbang_data[2];
+	bitbang_data[0].tms = 0;
+	bitbang_data[0].tdi = 1;
+	bitbang_data[1].tms = 0;
+	bitbang_data[1].tdi = 1;
+	bitbang.data = bitbang_data;
+	bitbang.length = 2;
+	ioctl(jtag_fd, JTAG_IOCBITBANG, &bitbang);
+	tdo0 = bitbang_data[0].tdo;
+	tdo1 = bitbang_data[1].tdo;
-- 
2.7.4