From d4c55bd4eeb6d9290025fa353d1787f18bca6ade Mon Sep 17 00:00:00 2001 From: "Corona, Ernesto" Date: Sun, 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 Signed-off-by: Corona, Ernesto Acked-by: Arnd Bergmann Cc: Jonathan Corbet Cc: Jiri Pirko Cc: Vadim Pasternak Cc: Steven A Filary Cc: Bryan Hunt --- v28->v29 Comments pointed by Steven Filary - 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 - 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 - 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 | 145 +++++++++++++++++++++++++++++++++++++ 3 files changed, 195 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 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]. + + 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 000000000000..6a5ec335e313 --- /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 000000000000..f5d4a1ded6cf --- /dev/null +++ b/Documentation/jtag/transactions @@ -0,0 +1,145 @@ +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_tap_state { + __u8 reset; + __u8 from; + __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_tap_state tap_state; + + tap_state.from = JTAG_STATE_TLRESET; + 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 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; + __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 +from: xfer from state can be current JTAG tap state saved by the driver + JTAG_STATE_CURRENT or in a multichain environment any state listed in + jtag_tapstate struct saved by your multichain controller software. +endstate: xfer end state after transaction finish + can be: any state listed in jtag_tapstate 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.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 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