diff options
author | Ernesto Corona <ernesto.corona@intel.com> | 2020-09-29 18:30:13 +0300 |
---|---|---|
committer | Jae Hyun Yoo <jae.hyun.yoo@linux.intel.com> | 2021-11-05 10:22:08 +0300 |
commit | ef68fb9689a2ffc7134d3717f459a1ecfe888509 (patch) | |
tree | 5f4c6c2c60c87292d5292ff5f7e410c67f9321fc | |
parent | 1223c4de89fbfbade4a44416e77c0a4c75b31e65 (diff) | |
download | linux-ef68fb9689a2ffc7134d3717f459a1ecfe888509.tar.xz |
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: Ernesto Corona <ernesto.corona@intel.com>
Acked-by: Arnd Bergmann <arnd@arndb.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Arnd Bergmann <arnd@arndb.de>
Cc: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Cc: Linus Walleij <linus.walleij@linaro.org>
Cc: Manivannan Sadhasivam <manivannan.sadhasivam@linaro.org>
Cc: Jeffrey Hugo <jhugo@codeaurora.org>
Cc: Steven Filary <steven.a.filary@intel.com>
Cc: Jiri Pirko <jiri@mellanox.com>
Cc: Vadim Pasternak <vadimp@mellanox.com>
Cc: Amithash Prasad <amithash@fb.com>
Cc: Patrick Williams <patrickw3@fb.com>
Cc: Rgrs <rgrs@protonmail.com>
-rw-r--r-- | Documentation/ABI/testing/jtag-dev | 23 | ||||
-rw-r--r-- | Documentation/index.rst | 1 | ||||
-rw-r--r-- | Documentation/jtag/index.rst | 18 | ||||
-rw-r--r-- | Documentation/jtag/jtag-summary.rst | 47 | ||||
-rw-r--r-- | Documentation/jtag/jtagdev.rst | 207 |
5 files changed, 296 insertions, 0 deletions
diff --git a/Documentation/ABI/testing/jtag-dev b/Documentation/ABI/testing/jtag-dev new file mode 100644 index 000000000000..423baab18761 --- /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/index.rst b/Documentation/index.rst index 54ce34fd6fbd..91f4f7923359 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -111,6 +111,7 @@ needed). iio/index isdn/index infiniband/index + jtag/index leds/index netlabel/index networking/index diff --git a/Documentation/jtag/index.rst b/Documentation/jtag/index.rst new file mode 100644 index 000000000000..8a2761d1c17e --- /dev/null +++ b/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` diff --git a/Documentation/jtag/jtag-summary.rst b/Documentation/jtag/jtag-summary.rst new file mode 100644 index 000000000000..050b16a9f801 --- /dev/null +++ b/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 +- Steven Filary +- Vadim Pasternak +- Jiri Pirko +- Oleksandr Shamray diff --git a/Documentation/jtag/jtagdev.rst b/Documentation/jtag/jtagdev.rst new file mode 100644 index 000000000000..c50ed2b85a07 --- /dev/null +++ b/Documentation/jtag/jtagdev.rst @@ -0,0 +1,207 @@ +.. 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_tap_state { + __u8 reset; + __u8 from; + __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_tapstate enum +:: + + enum jtag_tapstate { + 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_tap_state tap_state; + + tap_state.endstate = JTAG_STATE_IDLE; + tap_state.reset = 0; + tap_state.tck = data_p->tck; + usleep(25 * 1000); + ioctl(jtag_fd, JTAG_SIOCSTATE, &tap_state); + +JTAG_GIOCSTATUS +~~~~~~~~~~~~~~~ +Get JTAG TAPC current machine state +:: + + unsigned int jtag_fd; + jtag_tapstate tapstate; + ioctl(jtag_fd, JTAG_GIOCSTATUS, &tapstate); + +JTAG_IOCXFER +~~~~~~~~~~~~ +Send SDR/SIR transaction +:: + + struct jtag_xfer { + __u8 type; + __u8 direction; + __u8 from; + __u8 endstate; + __u32 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 + +from: jtag_tapstate enum representing the initial tap state of the chain before xfer. + +endstate: end state after transaction finish any of jtag_tapstate enum + +padding: padding configuration. See the following table with bitfield descriptions. + +=============== ========= ======= ===================================================== +Bit Field Bit begin Bit end Description +=============== ========= ======= ===================================================== +rsvd 25 31 Reserved, not used +pad data 24 24 Value used for pre and post padding. Either 1 or 0. +post pad count 12 23 Number of padding bits to be executed after transfer. +pre pad count 0 11 Number of padding bit to be executed before transfer. +=============== ========= ======= ===================================================== + +length: xfer data length in bits + +tdio : xfer data array + +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.from = JTAG_STATE_TLRESET; + 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 |