diff options
Diffstat (limited to 'fpga/xilinx/programmer/dependencies/libxsvf/README')
| -rw-r--r-- | fpga/xilinx/programmer/dependencies/libxsvf/README | 365 |
1 files changed, 365 insertions, 0 deletions
diff --git a/fpga/xilinx/programmer/dependencies/libxsvf/README b/fpga/xilinx/programmer/dependencies/libxsvf/README new file mode 100644 index 0000000..60d5aeb --- /dev/null +++ b/fpga/xilinx/programmer/dependencies/libxsvf/README @@ -0,0 +1,365 @@ + +Lib(X)SVF - A library for implementing SVF and XSVF JTAG players +****************************************************************** + +Please check the subversion repository for updates: +http://svn.clifford.at/libxsvf/trunk/ + +You also might want to have a look at the project homepage: +http://www.clifford.at/libxsvf/ + +In papers and reports, please refer to Lib(X)SVF as follows: "Clifford Wolf, +Lib(X)SVF: A library for implementing SVF and XSVF JTAG players. +http://www.clifford.at/libxsvf/", e.g. using the following BibTeX code: + +@MISC{LibXSVF, + author = {Clifford Wolf}, + title = {Lib(X)SVF: A library for implementing SVF and XSVF JTAG players}, + howpublished = "\url{http://www.clifford.at/libxsvf/}" +} + +Please send bug reports and fixes to <clifford@clifford.at>. + + +Copyright and Disclaimer +------------------------ + +Copyright (C) 2009 RIEGL Research ForschungsGmbH +Copyright (C) 2009 Clifford Wolf <clifford@clifford.at> + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + + +Introduction +------------ + +JTAG (IEEE 1149.1, aka "Boundary Scan", [1], [2]) is a standard IC +testing, debugging and programming port. + +SVF (Serial Vector Format, [3], [4]) is a file format for storing the +patterns that should be sent to the JTAG interface, as well as the +expected response. It is used as an exchange format between programms +that generate the JTAG input/output patterns and devices that can +physically talk to a JTAG interface. + +XSVF (Xilinx Serial Vector Format, [5]) is a binary variant of the SVF +file format, optimized but not limited to programming Xilinx FPGA and +CPLD devices. + +Often one wants to use an embedded host processor or microcontroller +to access the JTAG interface on an embedded device instead of using +an external JTAG probe. This library can be used to implement such a +solution. In addition to playing SVF and XSVF files this library is +also capable of scanning the devices in the JTAG chain. + +Lib(X)SVF is free software licensed under the ISC license (a licence +that is functionally equivalent to the 2-clause BSD license). + +[1] http://en.wikipedia.org/wiki/JTAG +[2] http://www.fpga4fun.com/JTAG.html +[3] http://en.wikipedia.org/wiki/Serial_Vector_Format +[4] http://www.asset-intertech.com/support/svf.pdf +[5] http://www.xilinx.com/bvdocs/appnotes/xapp503.pdf + + +Limitations and non-standard extensions +--------------------------------------- + +The SVF commands 'PIO' and 'PIOMAP' are unsupported. Any use of this +commands in an SVF input file is reported as error. + +The SVF 'RUNTEST' command is implemented in a limited manner: The +'MAXIMUM' time parameter is ignored. Combining 'SCK' with a time +parameter results in first executing the specified number of clock +pulses followed by a delay of the specified timespan, instead of +performing the clock cycles and the delay in parallel. + +The SVF commands 'HDR', 'HIR', 'SDR', 'SIR', 'TDR' and 'TIR' support +an additional non-standard 'RMASK' parameter. This is a mask for the +TDO bits, simmilar to the standard 'MASK' parameter. All TDO bits +marked using a '1' in 'RMASK' are reported back to the host application +using the the ret_tdo() callback function. This can be used to read +data (such as device serial numbers) using JTAG by providing SVF +templates. + + +Using and Porting +----------------- + +The library itself is written in plain C and does not depend on any +library calls or headers, not even from the standard C library. So it +can be ported easily even to restricted environment, such as embedded +systems. + +So far the libary has only been tested on 32 bit hosts. Using it on +16 bit processors might not be possible without performing some minor +fixes in the code. + +The program 'xsvftool-gpio' (see xsvftool-gpio.c) is a good example +of how to use the library. Please have a look at this program first. + +Note: See 'Host accessor macros' below for an alternative way of +integrating libxsvf into your host environment. + +The host application must provide an libxsvf_host struct as defined +in libxsvf.h. This struct contains some function pointers that must +be set to implementations of the following functions: + + int setup(struct libxsvf_host *h); + + This function is called by libxsvf to setup/initialize the + jtag interface. It is executed before any other libxsvf_host + callback function is called. + + This function should return 0 when setting up the jtag + interface went fine and -1 on an error. + + int shutdown(struct libxsvf_host *h); + + This function is called by libxsvf to shutdown the jtag + interface. No other libxsvf_host callback function will + be called after this function has been executed. + + This function should return 0 when shutting down the jtag + interface went fine and -1 on an error. + + void udelay(struct libxsvf_host *h, long usecs, int tms, long num_tck) + + A function that delays execution for at least the specified + number of microseconds. + + When the 'num_tck' argument is not 0 also the specified number tck + clock cycles (i.e. 1-0-1 transitions) must be generated with TMS set + to the value specified in the 'tms' argument. + + A simple implementation may perform the delay and the clock cycles + after another instead of parallel. This only has an impact on the + runtime of the player, not on its functionality. + + int getbyte(struct libxsvf_host *h); + + A function that returns the next byte from the input file + or -1 on end of file. + + int sync(struct libxsvf_host *h); + + This function is only needed when writing bindings for an asynchronous + hardware interface (see 'Using libxsvf with asynchronous interfaces' below). + + This function is optional and the function pointer may be set to a NULL + pointer on implementations using the simple synchronous interface. + + void pulse_tck(struct libxsvf_host *h, int tms, int tdi, int tdo, int rmask, int sync) + + This is the main JTAG I/O callback function. + It must perform the following tasks: + + * Set the tms line to the value specified in the 'tms' argument. + + * Set the tdi line to the value specified in the 'tdi' argument. + This argument may be '-1' to indicate that the value of the tdi + line is not important. In this case the tdi line may be set to + any value or may be left unchanged. + + * Create a negative pulse (1-0-1) on the JTAG TCK line. + + * Check the tdo line against the should-be value specified in + the 'tdo' argument. This argument may be '-1' to indicate that + the value of the tdo line doesn't need to be checked. + + * Store the current tdo value if the 'rmask' value is set to '1'. + This step may be ignored if the RMASK feature (see "Limitations + and non-standard extensions" above) is not used. + + The function must return the current value of the tdo line, or -1 on + a TDO-mismatch-error. + + A simple implementation of this function would look like this: + + --snip-- + int my_pulse_tck(struct libxsvf_host *h, int tms, int tdi, int tdo, int rmask, int sync) { + int line_tdo; + setPort(TMS, tms); + if (tdi >= 0) + setPort(TDI, tdi); + setPort(TCK, 0); + setPort(TCK, 1); + line_tdo = getPort(TDO); + return tdo < 0 || line_tdo == tdo ? line_tdo : -1; + } + --snap-- + + The 'sync' argument can safely be ignored unless you are writing + bindings for an asynchronous hardware interface (see 'Using libxsvf + with asynchronous interfaces' below). + + void pulse_sck(struct libxsvf_host *h); + + A function to create a pulse on the JTAG SCK line. + + This function is optional and the function pointer may + be set to a NULL pointer on implementations without an + SCK line. In this cases an SVF 'RUNTEST n SCK' command + has no effect. + + void set_trst(struct libxsvf_host *h, int v); + + A function to set the JTAG TRST line to the specified + value: + 1 ... drive the line high + 0 ... drive the line low + -1 ... do not drive the line (high impedance) + -2 ... got SVF 'TRST ABSENT' command + + This function is optional and the function pointer may + be set to a NULL pointer on implementations without an + TRST line. In this cases an SVF 'TRST' command has no + effect. + + int set_frequency(struct libxsvf_host *h, int v); + + A function to set the JTAG CLK frequency to the specified + value in Hz. This function should return 0 when setting + the frequency was successful and -1 on error. + + This function pointer is optional (may be set to NULL). + In this case an SVF FREQUENCY command always results in + an error. + + void report_tapstate(struct libxsvf_host *h); + + This function is called whenever the state of the TAP + state machine has changed. The TAP state can be read + using the h->tap_state enum. + + This function pointer is optional (may be set to NULL) + and is for debugging purposes only. + + void report_device(struct libxsvf_host *h, unsigned long idcode); + + This function is called in scan mode for each device found + in the JTAG chain. + + This function pointer is optional (may be set to NULL) + and is only called in the SCAN mode. + + void report_status(struct libxsvf_host *h, const char *message); + + This function is called each time before an SVF or XSVF + command is executed. + + This function pointer is optional (may be set to NULL) + and is for debugging purposes only. + + void report_error(struct libxsvf_host *h, const char *file, int line, const char *message); + + This function is called whenever an error is detected + in libxsvf. It is not optional and should provide a + way to notify a user about the error. + + void *realloc(struct libxsvf_host *h, void *ptr, int size, enum libxsvf_mem which); + + This function must provide a way to allocate dynamic + memory. In cases where there is a standard c library + it may be a simple wrapper for the realloc() function. + + The xsvftool-gpio command line option '-r' can be used to + auto-generate a realloc function for static buffers, based + on the requirements from an example svf or xsvf file. + Example given: + + ./xsvftool-gpio -r my_host_realloc -s demo.svf + + (Re-)allocation may fail. In this cases a NULL pointer + must be returned. The library then generates an error, + frees all resources and returns. + +After such a struct is prepared, the function libxsvf_play() +can be called, passing the libxsvf_host struct as first and the +mode (LIBXSVF_MODE_SVF, LIBXSVF_MODE_XSVF or LIBXSVF_MODE_SCAN) +as second argument. + +Example given: + + if (libxsvf_play(&h, LIBXSVF_MODE_XSVF) < 0) { + /* Error handling */ + } + +The libxsvf_host struct is passed back to all callback functions +and the 'user_data' member (a void pointer) can be used to pass +additional data (such as a file handle) to the callbacks. + + +Host accessor macros +-------------------- + +Despite its great flexibility, APIs based on callback functions +as the one used by libxsvf are unusual in the embedded community. +Basically because they introduce a slight overhead in the memory +footprint. + +For those who prefer a more direct integration with their host +environments libxsvf also provides 'host accessor macros' in the +libxsvf.h header file. Simply remove the callback functions from +the libxsvf_host struct and modify the LIBXSVF_HOST_ macros +to fit your needs. + + +Using libxsvf with asynchronous interfaces +------------------------------------------ + +This library has been designed at first for a register mapped bit banging +interface as it can be found on many microcontrollers or host CPUs. But +some interfaces might require the JTAG data to be send and recivied in +blocks and/or asynchronously. This is not trivial with this library because the +pulse_tck() callback function is expected to transfer one single bit at a time. +The solution to this is to buffer all data sent to pulse_tck() and always +return a valid status (i.e. 'tdo < 0 ? 1 : tdo') and do the transfers when the +buffer is full or when an interface shutdown is requested. + +However, some JTAG transaction must be performed synchronously (e.g. the last +transaction in an XSVF XREPEAT data shift. In this cases pulse_tck() is called +with the 'sync' argument set to 1. The pulse_tck() function must then perform +all buffered JTAG transactions and return the actual tdo value for this last +JTAG transaction or -1 if an error was detected before. + +An asynchronous interface binding also must implement the sync() function. It +must perform all buffered JTAG transactions and return -1 if a TDO error was +detected an 0 otherwise. + +Note: The returncode of pulse_tck is not checked in all conditions! So whenever +an error is detected all further calls to pulse_tck() up to and including +the next call of pulse_tck() with the 'sync' argument set or the next call to +sync() or shutdown() must return -1. + +Have a look at the example program 'xsvftool-ft232h.c' for a reference +implementation. + + +Stripping down libxsvf +---------------------- + +It is possible to disable SVF, XSVF and/or SCAN support by setting the +LIBXSVF_WITHOUT_SVF, LIBXSVF_WITHOUT_XSVF or LIBXSVF_WITHOUT_SCAN +defines. In this cases one would not want to link against svf.o, xsvf.o +or scan.o. + +One does not need to link agains statename.o and memname.o if the +libxsvf_state2str() and libxsvf_mem2str() functions are not needed. +Usually this functions are used for debugging purposes only. + +It is possible to modify the LIBXSVF_HOST_REPORT_STATUS() and +LIBXSVF_HOST_REPORT_ERROR() macros in libxsvf.h to be empty +instructions. This drastically reduces the number of string +constants in the code. + |