SPREADSHEET PIN_REPORT_TYPES
- Bill OLeary
GENERIC_CSV_FILE and SPREADSHEET
The SPREADSHEET and GENERIC_CSV_FILE allow the user to provide pinData using a very flexible spreadsheet format
The user must provide PartBuilder with extra configuration details to detail the layout of pinData within the spreadsheet.
The PIN_NUM_TYPE_FILE is actually a subset of the GENERIC_CSV_FILE, where the fields are predefined.
Unlike the PIN_NUM_TYPE_FILE, in the GENERIC_CSV_FILE, Multiple Pin Names and Pin Numbers can be provided in one cell of the spreadsheet.
The GENERIC_CSV_FILE the user to create a .csv file from the source excel or openOffice spreadsheet.
In the SPREADSHEET flow (added after v18.11.1) , partBuilder can read the native spreadsheet file without the intermediate save step, and it also allows the user to merge several spreadsheet Tabs without any intervention
Creating a spreadsheet from a PDF File
There are many free web-based utilities to create a spreadsheet from a pdf file. CadEnhance recommends this site in particular:
https://online2pdf.com/pdf2excel because it allows the user to select a pdf file and restrict the extraction to selected page ranges.
See Creating a SpreadSheet from a PDF File for more information
Configuring PartBuilder to read a SPREADSHEET
PartBuilder must be told how the pin_data is organized in the actual spreadsheet. This is accomplished using the Extra Config Options GUI which can be accessed by the More Part Config Settings Button on the Main GUI.
SPREADSHEET_TAB_NAMES (for SPREADSHEET only)
When the PIN_REPORT_TYPE is set to SPREADSHEET, the input spreadsheet may contain several tabs of information.
The user must tell PartBuilder which Tabs to use, and if the user enters Multiple Tab_Names separated by commas, PartBuilder will merge the data on each of the Tabs into one larger report.
If there is only one Tab defined in the spreadsheet, PartBuilder will figure this out on its own.
PIN_INFORMATION_FIELDS (PIF):
PartBuilder expects to find groups of related PIN_INFORMATION_FIELDS from the SPREADSHEET. The PIN_INFO_FIELDS that PartBuilder recognizes are:
| PIN_INFORMATION_FIELD (PIF) Name | Description | Notes |
|---|---|---|
| PIN_NUM | A single Pin number or a range of pin numbers | |
| PIN_NAME | A single Pin Name, A Vectored Pin Name eg. DQ[7:0] or a group of PIN_NAMES eg sigA,SigB,SigC | If a Vectored Pin_Name is detected, PartBuilder expects to find the matching number of PIN_NUMS in the related PIN_NUM Field. For example if the PIN_NAME is DQ[7:0] PartBuilder will expect to find 8 Pin Numbers in the PIN_NUM field if the PIN_NAME Field contained sigA,sigB,sigC... PartBuilder will expect to find 3 Pin Numbers in the PIN_NUM Field |
| MERGE_PIN_NAME | The PIN_NAME can be split across multiple columns in this case partBuilder will concatenate the PIN_NAMES from multiple columns to build the full PIN_NAME | PartBuilder uses the value of the GEN_CSV_PN_MERGE_CHAR (which defaults to an underscore '_' to join the elements of a PinName together |
| PIN_TYPE | Usually a Single Pin Type like Input, Inout, Output, Power, Ground | The PIN_TYPE field can contain 1 PIN_TYPE for all the PINS in the PIN_NAME field or it can have individual pin types |
| IO_STD | The IO Standard for a PIN Like LVCMOS_18 or TTL, HSTL | |
| PIN_DELAY | the PIN_DELAY in length or time | |
| DESCRIPTION | PartBuilder will store this field as the pin Description | Nothing is done with the description right now, but future revisions of PartBuilder may use it. |
| SKIP | PartBuilder will SKIP this column and also make sure it is empty | If the column is not empty, PartBuilder will report an error. |
| IGNORE | PartBuilder will IGNORE this column and doesn't care if there is any data provided | Note that you can also add a digit after the IGNORE or SKIP (like IGNORE2 or SKIP3) to bypass multiple columns |
PIN_INFORMATION_FIELD_GROUPS (PIF_GROUP)
PartBuilder expects to find a minimum of 2 PIN_INFORMATION_FIELDS (PIF) for each Pin in a row. A PIN_NUM and PIN_NAME field must be provided for each pin. The related sets of columns for each pin are called PIN_INFORMATION_FIELD_GROUPS (PIF_GROUP) which are entered as colon ':' separated sets of valid individual PIFS.
here are some example PIF_GROUPS
| Example PIF_GROUP defintions | notes |
|---|---|
| PIN_NAME:PIN_NUM:PIN_TYPE | pretty self explanatory... The 1st column contains the PIN_NAME PIF, the next is the PIN_NUM PIF, and the last is the PIN_TYPE PIF. |
| PIN_NAME:PIN_NUM:MERGE_PIN_NAME:PIN_TYPE | The MERGE_PIN_NAME PIF in the 3rd column will be concatenated to the PIN_NAME PIF from the 1st Column to build the actual PIN_NAME used by PartBuilder. |
| SKIP:IGNORE | These 2 columns will be skipped, but the SKIP one will be checked to make sure its empty while the IGNORE one can contain any text. |
REPEAT_COUNT=> Modifer
To make the entry less cumbersome, PartBuilder also can also accept a REPEAT_COUNT=>PIF_GROUP modifer to describe a repeating set of PIF_GROUPs, which is what is used in the GENERIC_CSV_COLUMN_DEF Entry above.
This looks like:
REPEAT_COUNT=>PIF_GROUP
| example | |
|---|---|
| 4=>PIN_NUM:PIN_TYPE | Expect data for 4 PIF_GROUPS of pin data, containing the PIN_NUM PIF and the PIN_TYPE PIF |
GENERIC_CSV_COLUMN_DEF:
PartBuilder will read one row of the spreadsheet at a time, and looks to extract the PIN_INFORMATION_FIELDS (PIF), arranged in any order in spreadsheet columns.
The GENERIC_CSV_COLUMN_DEF Entry, is used to tell PartBuilder which columns contain which PIFS. It is entered as comma separated PIF_GROUPS, with one PIF_GROUP for each set of pin data present in a row.
PIF_GROUP1,PIF_GROUP2,...PIF_GROUPn
| example | Notes and example data in the spreadSheet | ||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| PIN_NUM:PIN_NAME:PIN_TYPE:IO_STD | PartBuilder will look for one pin in each row and extract the PIN_NUM from the first column, PIN_NAME from the 2nd column, PIN_TYPE from the 3rd column and IO_STD for the 4th column. note on the 2nd row,
| ||||||||||||||||||||||||||||||||||||||
| PIN_NUM:PIN_NAME,PIN_NUM:PIN_NAME | Since there is a comma separating 2 PIF_GROUPS, PartBuilder will look for data for 2 pins from each row, and extract the PIN_NUM and PIN_NAME for the first pin from columns 1 and 2 and the PIN_NUM and PIN_NAME for the 2nd Pin from columns 2 and columns 3. PartBuilder will build up pin_information for each pin in a row, one at a time, and verify that it contains at least a PIN_NAME and PIN_NUM. PartBuilder will accept a row with sparse pin (so if columns 1 and 2 were empty and columns 3 and 4 contained a PIN_NUM and PIN_NAME it would still pull the existing pin from that row.
| ||||||||||||||||||||||||||||||||||||||
| 2=>PIN_NUM:PIN_NAME | exactly the same as the example above, just using the REPEAT_COUNT=> modifier
| ||||||||||||||||||||||||||||||||||||||
| 4=>PIN_NAME:PIN_NUM:SKIP | Here PartBuilder will look for data for up-to 4 pins per row, it will skip every 3rd column (and also make sure that that column is blank
| ||||||||||||||||||||||||||||||||||||||
GENERIC_CSV_HDR_ID
The GENERIC_CSV_HDR_ID tells partBuilder what row to skip because they contain Header fields.
PartBuilder expects to find valid pin data on every occupied row following the Header Row. (It will also skip any row that starts with a '#' so the user may easily comment out rows they want partBuilder to ignore)
It is entered as ROW# (example: ROW3)
After v18.11.1, PartBuilder relies less on the GENERIC_CSV_HDR_ID and will skip data in a PIF_GROUP automatically if it determines a selected column does not contain the proper type of information. (For instance it will make sure a PIN_NUM column contains a valid list of PinNumbers, and can even check to make sure the PIN_NUMBERS in a column are actually supposed to be in the device (see the PinData Verification Checks page)
GENERIC_PIN_TYPE_MAPPING ENTRY
The GENERIC_PIN_TYPE_MAPPING is provided to translate the PIN_TYPE provided in a datasheet to a PIN_TYPE that PartBuilder recognizes. It is entered as a comma separated group of PIN_TYPE Translations. PartBuilder recognizes the following PIN_TYPES:
| PartBuilder Standard Pin Types |
|---|
| INPUT, OUTPUT, INOUT |
| POWER, GROUND |
| NO_CONNECT |
| ANALOG |
If the input CSV file uses different names for these PIN_TYPES, the GENERIC_PIN_TYPE_MAPPING entry is used to provide the Translation.
For instance if the input data sheet denotes INPUTS as I, OUTPUTS as O, INOUTS as BI, GROUNDs as GND and POWER PINS as PWR,
The GENERIC_PIN_TYPE_MAPPING would be set to I:INPUT,O:OUTPUT,BI:INOUT,GND:GROUND,PWR:POWER
Until v18.11.1, The GENERIC_PIN_TYPE_MAPPING fields only worked as exact matches.
In later versions, more flexibility is added so that each PIN_TYPE Translation can be a regularExpression and will change pinTypes if the input pinType contains the PinType match (instead of exactly matching)
| GENERIC_PIN_TYPE_MAPPING | Splits into | Effective Rules | example match |
|---|---|---|---|
| ^O.*:OUTPUT,^I.*:INPUT,^B.*:INOUT,^reserved:INOUT | ^O.*:OUTPUT | any PinType that starts with O will be changed to OUTPUT, | O1,O3,OUT |
| ^I.*:INPUT | any PinType that starts with I will be changed to INPUT | I7,In6,IN,INP | |
| ,^B.*:INOUT | any PinType that starts with B will be changed to INOUT | B6,BI,BIDI | |
| ^reserved:INOUT | any PinType that starts with reserved will be changed to INOUT | reserved1,reservedBI |
More Controls to Filter Out PinData
CadEnhance believes that the user should avoid modifying the original PIN_DATA reports obtained from a vendor if at all possible.
The user may have to obtain an updated version of the pinData from the vendor and would be forced to make the same edits each time.
It is better to provide controls to tell PartBuilder to ignore or include certain rows or individual pins, and be able to store that rule in the partConfig file.
With that in mind, the folllowing entries allow the user extra control to allow or disallow certain pinData without modifying the spreadsheet.
EXCLUDE_PIN_NUMS_MATCHING:
This Setting can be used to exclude pins from the spreadsheet where the PIN_NUMBER matches any of the specified patterns.
The reason it was created was to handle tables that describe multiple packages for the same device
where the pin might not exist in some of the packages and might be given as '-' or something else.
Multiple patterns separated by commas can be provided.
This can be helpful when PartBuilder detects Duplicate PinNumbers or PinNames
and you don't want to modify the vendor provided pinData
EXCLUDE_PIN_NAMES_MATCHING:
This Setting can be used to exclude pins from any PIN_REPORT_TYPE where the PIN_NAME matches any of the specified patterns.
This is a natural companion to the EXCLUDE_PIN_NUMS_MATCHING config variable...
Multiple patterns separated by commas can be providedThis can be helpful when PartBuilder detects Duplicate PinNumbers or PinNames
and you don't want to modify the vendor provided pinData
NO_POP_PIN_MATCHES:
This Setting is can be used to identify pins by PIN_NAME that shouldn't be added to the pinout...
The default is: ^-$,!NO_PIN which means any pinName that contains just '-' or contains !NO_PIN (which would typically be added by editing a spreadsheet)
If a PinName in the PIN_NAME column of a spreadsheet matches any of these patterns, They will be treated as empty pin slots, and will not be added as a pin
This allows you to have a spreadsheet with
| PinNum | PinName | PinNum | PinName | PinNum | PinName |
|---|---|---|---|---|---|
| A1 | gnd | B1 | - | C1 | vcc |
| A3 | - | B3 | gnd | C3 | !NO_PIN |
where Pins B1,A3 and C3 will not be added to the pinout (or PinCount) because the PIN_NAME matches the NO_POP_PIN_MATCHES setting
A3 is higlighted because the user would probably have added the !NO_PIN entry manually
These patterns could be present in the pin spreadsheet OR the user can edit the pinName cells and add this pattern if needed.
This should work for all other types of PIN_REPORTS, the check is done when adding the pin to the pinout list
VALID_PIN_NUM_MATCHES:
When reading a SPREADSHEET, using SPREADSHEET or GENERIC_CSV PIN_REPORT_TYPE,PartBuilder validates the contents of the PIN_NUM column to make sure they contain
normal pinNumbers like 1 to 100 or A5, AA22. This makes it easier to parse the spreadsheets and throw out rows that don't seem to conform.
Some parts may have pin numbers that do not conform to those rules like: GND_TAB if they do and you are missing pins, you will need to add those special pins to this Entry
(separating each match by a ',')
It will be used as a regular expression to match the pin so the part had GND_TAB1...GND_TAB25 pins
GND_TAB would validate all of them.
This Entry is not needed if the user defines the expected PIns using the newer partBuilder capabilites described in the PinData Verification Checks page, since PartBuilder will accept any pins that are entered in the PCHK_DEVICE_PIN_NUMBERS entry