TICSPRO-SW: TCS and INI file format questions

All of our software in TP1.x is covered under the Source and Binary Code Internal Use License Agreement, which is included in the installation directory as Internal Use License.pdf. I've reproduced it here.

Internal Use License.pdf

Let me be clear that the full text of the license agreement lays out in great detail what is and is not considered use of our software under the terms we specify, and the summary below is NOT comprehensive or authoritative. A lot of the license text should be unsurprising, such as the parts about warranty/limitations and indemnification. I'll try to highlight things that might come up for you:

• You are granted a license to, among other things, prepare derivative works of our software (i.e. TICS Pro and the profile data). Provided the derivative works do not include the actual files distributed to you by TI, I see nothing which prevents you from referencing their location in an installation, or describing how to use your scripts or libraries with files provided by TI (including, as noted, example input excerpts).
• You're free to specify your own license for your own derivative works, with the understanding that your license doesn't obligate TI to behave in a way inconsistent with our own license terms. This means:
  • TICS Pro is still under the Source and Binary Code Internal Use License Agreement, and TI isn't obligated to provide our software to users of your derivative works.
  • You should not redistribute our software yourself. A strict reading of our license terms suggests that the only authorized redistribution of our software is internally, to employees and contractors whose job performance requires access. In practice, we clearly allow distribution of tcs/tcb files (particularly as needed for debugging), and we have posted other INIs on the E2E forums in the past, so I don't see any confidentiality problem with providing de minimis example excerpts and XML transformed outputs for testing or demonstration. Likely of greater concern is potential for export control violation - TI takes measures to protect the E2E forums and the website from unauthorized exports, but it's not clear this is possible with all means of open source software distribution. If you're including data about our devices in your own software (even just register information that is otherwise publicly available on TI.com), there's a slim but alarming possibility this could someday constitute an unauthorized export. In my opinion, it's probably safest to provide any examples and/or tests using arbitrary generated data that avoids any specific product information.
  • TI isn't officially licensing, endorsing, or claiming any responsibility for your derivative works. Neither are you obligated to provide your derivative works or any maintenance for them to TI. I'm happy to suggest your work to others if it seems like it meets their needs, and I have no problem offering guidance or answering questions over E2E that would make your derivative works better/easier to use/etc - just making it clear that this is voluntary collaboration rather than contractual obligation.
• Our INI format isn't proprietary, confidential, trade secret, patented, etc. It's just publicly undocumented, as there's not often been a compelling reason to publicly document it. So there's no problem distributing your own software package that explains and/or manipulates the format and function of the INIs we distribute in our software.

Jennifer Bernal said:

---> Yes.

Yes... except LMX248xE devices. In order to pack two divider writes into one register transaction, the designers decided that R0 uniquely contained 31 bits of data and one bit of address (forced to 0); all other registers have 28 bits of data and 4 bits of address (with one of the 4 address bits forced to 1). TP1.x special-cases any part that matches these part names to handle the R0 export correctly.

Hopefully this never comes up for you... but it's a limitation other users of your software may need to be aware of.

Additionally, when importing the hex register data, several formats are accepted (including just a list of newline-separated hex-encoded values). I've reproduced the regexes below, with examples. Note that we always favor the register address extracted from the hex-encoded value, and report any mismatch with decimal register names.

/// CASE A (decimal reg#)   "R0 0x000000"
/// CASE B (hex reg#)       "R0x0 0x000000"
/// CASE C (no reg num)     "0x000000"
/// 
/// With mask
/// CASE A (decimal reg#)   "R0 0x000000 & 0x0000"
/// CASE B (hex reg#)       "R0x0 0x000000 & 0x0000"
/// CASE C (no reg num)     "0x000000 & 0x0000"
Regex casea = new Regex("^(R[0-9]+)[ \t]+(0x[0-9a-fA-F]+)[ \t]*&?[ \t]*(0x[0-9a-fA-F]+)?");
Regex caseb = new Regex("^(R0x[0-9a-fA-F]+)[ \t]+(0x[0-9a-fA-F]+)[ \t]*&?[ \t]*(0x[0-9a-fA-F]+)?");
Regex casec = new Regex("^(0x[0-9a-fA-F]+)[ \t]*&?[ \t]*(0x[0-9a-fA-F]+)?");

George Joseph said:

* Generating the EEPROM map isn't quite so simple but still straightforward...  Run through the [EEPROM_EETYPE_DEFINITION] section in the device's ini file, looking each field name up in the [BITS] section to get its register, offset and length, getting the values from the tcs file [MODES] section, then packing them into contiguous bytes.  From my experimentation this looks to produce the exact same results as doing a eeprom map export from TICS Pro but I wanted to confirm.

Contiguous bytes, it turns out, is not necessarily correct, but it is valid for all publicly released TICS Pro devices as far as I know.

Not every register field with EEPROM backing is 100% mapped to every EEPROM location. I recall that several devices only include partial contents of the I2C_ADDR field (or whatever it's called), and LMK5B33216 family has several dividers and output muxes that are not fully captured in EEPROM. Be careful, as this may introduce surprising offsets on some devices.

I recall there were no guarantees that bytewise stayed the same between different parts or between regmap and eeprom, and I think the CDCI6214 and CDCE6214 may have had different endianness within the same register/eeprom map. I think this is usually taken care of by the values in the EEPROM_EETYPE_DEFINITION corresponding to field names, but...

• Some fields in EEPROM don't exist in the [BITS] section and are not mapped to any register. I think this is mostly for spare bytes or user notes.
• I think not all EEPROM devices use the names - they may attempt to define semantically meaningful spans (with angle brackets, I think). This means you sometimes have to fully parse the field representation in the bits section, including all the linkedbits; then convert the register data to a field vector; then convert the vector back to EEPROM data in the appropriate segments. In other words, it's not always as simple as just grabbing the chunk of the register listed by the matching field name.

When constructing multi-register fields, the LINKEDBITS option in the INI is the authoritative name of the related register. Do not assume that the field names follow any standard - I'm no longer certain which, but some devices use angle brackets instead of square brackets in the name for field subspan differentiation, and I think some fields just don't have any subspan embedded in the name. I also recall that linkedbits was basically backward of how it made sense to do it, and vectorizing linkedbits required building a dictionary of field -> linkedbits, then inverting keys and values to determine the origin field (which is always referenced by a linkedbits option, but has no linkedbits option itself).

Some fields are in EEPROM multiple times for multiple register pages. I believe the layout of pages on the same publicly released TICS Pro devices should be identical, but there are no guarantees of this at a design level, so it's best not to assume this is the case. There are publicly released devices with e-fuse instead of EEPROM that do violate identical page layout assumptions.

I am unsure if padding bits represent actual usable EEPROM on-die. My assumption is they do not, since we regularly optimize die area and EEPROM is big. This may vary part-to-part.

---

In TP2, the EEPROM-related sections get a treatment similar to the current TP1.x [BITS] section, with more explicit documentation of the address, offset, span width, and page information on a per-field basis, as well as more explicit documentation of the structure. Importantly, the TP2 EEPROM grammar will not be an ad-hoc invention with dramatic per-part variations - the sections should have a consistent grammar and expressible rules followed by all devices. At some point, there will also be external APIs for interacting with the EEPROM.