Skip to content

Commit

Permalink
Lots of Doxygen comment improvements. Made some functions protected t…
Browse files Browse the repository at this point in the history
…hat were incorrectly public.
  • Loading branch information
azonenberg committed Aug 3, 2018
1 parent 68b7060 commit 5ba737d
Show file tree
Hide file tree
Showing 9 changed files with 212 additions and 68 deletions.
13 changes: 9 additions & 4 deletions DigilentJtagInterface.h
Expand Up @@ -2,7 +2,7 @@
* *
* ANTIKERNEL v0.1 *
* *
* Copyright (c) 2012-2016 Andrew D. Zonenberg *
* Copyright (c) 2012-2018 Andrew D. Zonenberg *
* All rights reserved. *
* *
* Redistribution and use in source and binary forms, with or without modification, are permitted provided that the *
Expand Down Expand Up @@ -39,9 +39,12 @@
#ifdef HAVE_DJTG

/**
@brief A JTAG adapter exposed through the Digilent Adept SDK
@brief A JTAG adapter exposed through the Digilent Adept SDK.
\ingroup libjtaghal
This includes Digilent-branded dev boards, Digilent-adapter cables such as the HS1, and OEM modules such as the
JTAG-SMT2 which may be integrated into third party boards.
\ingroup interfaces
*/
class DigilentJtagInterface : public JtagInterface
{
Expand All @@ -65,9 +68,11 @@ class DigilentJtagInterface : public JtagInterface

//Low-level JTAG interface
virtual void ShiftData(bool last_tms, const unsigned char* send_data, unsigned char* rcv_data, size_t count);
virtual void ShiftTMS(bool tdi, const unsigned char* send_data, size_t count);
virtual void SendDummyClocks(size_t n);

protected:
virtual void ShiftTMS(bool tdi, const unsigned char* send_data, size_t count);

protected:

///@brief The adapter's name
Expand Down
2 changes: 1 addition & 1 deletion Doxyfile
Expand Up @@ -2099,7 +2099,7 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

PREDEFINED =
PREDEFINED = HAVE_FTD2XX HAVE_DJTG

# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
Expand Down
62 changes: 46 additions & 16 deletions FTDIJtagInterface.cpp
Expand Up @@ -2,7 +2,7 @@
* *
* ANTIKERNEL v0.1 *
* *
* Copyright (c) 2012-2016 Andrew D. Zonenberg *
* Copyright (c) 2012-2018 Andrew D. Zonenberg *
* All rights reserved. *
* *
* Redistribution and use in source and binary forms, with or without modification, are permitted provided that the *
Expand Down Expand Up @@ -102,7 +102,7 @@ string FTDIJtagInterface::GetAPIVersion()
}

/**
@brief Gets the number of interfaces on the system (may include non-JTAG-capable devices)
@brief Gets the number of FTDI devices on the system (may include non-JTAG-capable devices)
@throw JtagException if the FTD2xx call fails
Expand Down Expand Up @@ -130,6 +130,18 @@ int FTDIJtagInterface::GetInterfaceCount()
return ndev_raw;
}

/**
@brief Checks if the requested FTDI device has a MPSSE (and is thus capable of being used for JTAG)
Note that this function cannot tell if an MPSSE-capable chipset is actually configured for use as JTAG or
as something else.
@throw JtagException if the index is invalid or data could not be read
@param index Zero-based index of the device to test
@return True if the device has a MPSSE, false otherwise.
*/
bool FTDIJtagInterface::IsJtagCapable(int index)
{
FT_STATUS err = FT_OK;
Expand All @@ -148,7 +160,6 @@ bool FTDIJtagInterface::IsJtagCapable(int index)
}

LogDebug("device %d type %d desc %s serial %s flags %d\n", index, type, desc, serial, flags);
//return true;

if( (type == FT_DEVICE_2232H) || (type == FT_DEVICE_4232H) || (type == FT_DEVICE_232H) )
return true;
Expand All @@ -159,11 +170,13 @@ bool FTDIJtagInterface::IsJtagCapable(int index)
/**
@brief Returns the description of the Nth device
@param index Zero-based index of the device to test
@throw JtagException if the index is invalid or data could not be read
@return Serial number string
*/
std::string FTDIJtagInterface::GetSerialNumber(int index)
string FTDIJtagInterface::GetSerialNumber(int index)
{
char serial[16];
FT_STATUS err = FT_OK;
Expand All @@ -183,7 +196,7 @@ std::string FTDIJtagInterface::GetSerialNumber(int index)
@return Description string
*/
std::string FTDIJtagInterface::GetDescription(int index)
string FTDIJtagInterface::GetDescription(int index)
{
char desc[64];
FT_STATUS err = FT_OK;
Expand Down Expand Up @@ -219,7 +232,7 @@ int FTDIJtagInterface::GetDefaultFrequency(int /*index*/)
@param serial Serial number of the device to connect to
@param layout Adapter layout to use
*/
FTDIJtagInterface::FTDIJtagInterface(const std::string& serial, const std::string& layout)
FTDIJtagInterface::FTDIJtagInterface(const string& serial, const string& layout)
{
//Enable use of azonenberg's custom PID
FT_STATUS err = FT_OK;
Expand Down Expand Up @@ -266,7 +279,7 @@ FTDIJtagInterface::FTDIJtagInterface(const std::string& serial, const std::strin
/**
@brief Shared initialization used by all constructors
*/
void FTDIJtagInterface::SharedCtorInit(uint32_t type, const std::string& layout)
void FTDIJtagInterface::SharedCtorInit(uint32_t type, const string& layout)
{
FT_STATUS err = FT_OK;

Expand Down Expand Up @@ -531,7 +544,9 @@ void FTDIJtagInterface::WriteData(const void* data, size_t bytesToWrite)
}

/**
@brief Wrapper around FT_Write()
@brief Wrapper around FT_Write() to push the provided data buffer to hardware.
Performs repeated write calls as needed to ensure the entire buffer is written.
@throw JtagException on failure
Expand Down Expand Up @@ -573,7 +588,7 @@ void FTDIJtagInterface::WriteDataRaw(const void* data, size_t bytesToWrite)
}

/**
@brief Wrapper around FT_Write()
@brief Wrapper around WriteData() to send a single byte
@throw JtagException on failure
Expand All @@ -585,7 +600,7 @@ void FTDIJtagInterface::WriteData(unsigned char cmd)
}

/**
@brief Wrapper around FT_Read()
@brief Wrapper around FT_Read() to work around some driver / API bugs
@throw JtagException on failure
Expand Down Expand Up @@ -664,23 +679,23 @@ void FTDIJtagInterface::ReadData(void* data, size_t bytesToRead)
/**
@brief Gets the manufacturer-assigned name for this programming adapter
*/
std::string FTDIJtagInterface::GetName()
string FTDIJtagInterface::GetName()
{
return m_name;
}

/**
@brief Gets the manufacturer-assigned serial number for this programming adapter
*/
std::string FTDIJtagInterface::GetSerial()
string FTDIJtagInterface::GetSerial()
{
return m_serial;
}

/**
@brief Gets the user-assigned name for this programming adapter
*/
std::string FTDIJtagInterface::GetUserID()
string FTDIJtagInterface::GetUserID()
{
return m_userid;
}
Expand Down Expand Up @@ -748,7 +763,7 @@ void FTDIJtagInterface::ShiftData(bool last_tms, const unsigned char* send_data,

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// Generate and send the command packet for the rest of the data
std::vector<unsigned char> cmd;
vector<unsigned char> cmd;
GenerateShiftPacket(send_data, count, want_read, last_tms, cmd);
WriteData(&cmd[0], cmd.size());

Expand Down Expand Up @@ -777,7 +792,7 @@ bool FTDIJtagInterface::ShiftDataWriteOnly( bool last_tms,
}

//Otherwise, send the write
std::vector<unsigned char> cmd;
vector<unsigned char> cmd;
GenerateShiftPacket(send_data, count, (rcv_data != NULL), last_tms, cmd);
WriteData(&cmd[0], cmd.size());
return true;
Expand All @@ -793,6 +808,12 @@ bool FTDIJtagInterface::ShiftDataReadOnly(unsigned char* rcv_data, size_t count)
return true;
}

/**
@brief Reads back data from a prior transaction
@param rcv_data Output data buffer
@param count Number of bits to read
*/
void FTDIJtagInterface::DoReadback(unsigned char* rcv_data, size_t count)
{
int bytes_left = count / 8;
Expand Down Expand Up @@ -827,11 +848,20 @@ void FTDIJtagInterface::DoReadback(unsigned char* rcv_data, size_t count)
PokeBit(rcv_data, nbit, (tmp & 0x80) ? true : false);
}

/**
@brief Generates the MPSSE commands for a shift operation
@param send_data Data to send
@param count Number of bits to send (not bytes)
@param want_read True if read data is needed, false for a write-only transaction
@param last_tms TMS value to use at the end of the shift operation (all other bits have TMS=0)
@param cmd_out The generated command buffer
*/
void FTDIJtagInterface::GenerateShiftPacket(
const unsigned char* send_data, size_t count,
bool want_read,
bool last_tms,
std::vector<unsigned char>& cmd_out)
vector<unsigned char>& cmd_out)
{
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
//Bulk data transfer is done. We now have less than 4KB left, but it might not be an even number of bytes
Expand Down
46 changes: 31 additions & 15 deletions FTDIJtagInterface.h
Expand Up @@ -43,21 +43,33 @@
/**
@brief A JTAG adapter using the FTDI chipset, accessed through libftd2xx (proprietary driver from FTDI)
This adapter supports split scanning and queues up to 4096 bytes of command+data before comitting to hardware.
GPIO pin mapping:
0 GPIOL0 (ADBUS4)
1 GPIOL1 (ADBUS5)
2 GPIOL2 (ADBUS6)
3 GPIOL3 (ADBUS7)
4 GPIOH0 (ACBUS0)
5 GPIOH1 (ACBUS1)
6 GPIOH2 (ACBUS2)
7 GPIOH3 (ACBUS3)
8 GPIOH4 (ACBUS4)
9 GPIOH5 (ACBUS5)
10 GPIOH6 (ACBUS6)
11 GPIOH7 (ACBUS7)
\ingroup libjtaghal
Index | Name
--------|--------
0 | GPIOL0 (ADBUS4)
1 | GPIOL1 (ADBUS5)
2 | GPIOL2 (ADBUS6)
3 | GPIOL3 (ADBUS7)
4 | GPIOH0 (ACBUS0)
5 | GPIOH1 (ACBUS1)
6 | GPIOH2 (ACBUS2)
7 | GPIOH3 (ACBUS3)
8 | GPIOH4 (ACBUS4)
9 | GPIOH5 (ACBUS5)
10 | GPIOH6 (ACBUS6)
11 | GPIOH7 (ACBUS7)
Supported layouts:
Name | Example hardware | Pin configuration
-----|------------------|--------------------
hs1 | Digilent JTAG-HS1, Digilent JTAG-SMT2, azonenberg's usb-jtag-mini | ADBUS7 is active-high output enable
jtagkey | Amontec JTAGkey, Bus Blaster w/ JTAGkey compatible buffer | ADBUS4 is active-low output enable, ACBUS0 is TRST_N, ACBUS2 is active-low output enable for TRST_N
\ingroup interfaces
*/
class FTDIJtagInterface : public JtagInterface
, public GPIOInterface
Expand All @@ -81,15 +93,18 @@ class FTDIJtagInterface : public JtagInterface

//Low-level JTAG interface
virtual void ShiftData(bool last_tms, const unsigned char* send_data, unsigned char* rcv_data, size_t count);
virtual void ShiftTMS(bool tdi, const unsigned char* send_data, size_t count);
virtual void SendDummyClocks(size_t n);
virtual void SendDummyClocksDeferred(size_t n);
virtual void Commit();
virtual bool IsSplitScanSupported();
virtual bool ShiftDataWriteOnly(bool last_tms, const unsigned char* send_data, unsigned char* rcv_data, size_t count);
virtual bool ShiftDataReadOnly(unsigned char* rcv_data, size_t count);

protected:
virtual void ShiftTMS(bool tdi, const unsigned char* send_data, size_t count);

//GPIO stuff
public:
virtual void ReadGpioState();
virtual void WriteGpioState();

Expand All @@ -102,6 +117,7 @@ class FTDIJtagInterface : public JtagInterface
std::vector<unsigned char>& cmd_out);
void DoReadback(unsigned char* rcv_data, size_t count);

///@brief Buffer of data queued for the adapter, but not yet sent
std::vector<unsigned char> m_writeBuffer;

protected:
Expand Down

0 comments on commit 5ba737d

Please sign in to comment.