# File format of WinPic's PIC device list

## The file DEVICES.INI

This file can be modified to make WinPic support a new PIC device. To add support for a new device which is not directly supported by WinPic,

- Create a backup copy of the file DEVICES.INI
- Load the DEVICES.INI file with a text editor like Notepad.
- Add a new section for your the new device, like [PIC16F9999]. The easiest way to achieve this is block-copy another section for a similar device, rename the section header and modify all parameters which are different in the new device.
- Save the modified DEVICES.INI file
- Restart WinPic

The new device should appear in the device list now. If not, there may be something wrong in the file - usually a missing entry in the [Devices] section, so WinPic does not know that there is a new section in the file. (Reason: Its too complicated to check which "sections" are present in an INI-file. WinPic checks all "devX=NAME" entries in the section [Devices] to find out which devices are defined in the file). Device definitions in DEVICES.INI always override the definitions in the hard-coded "built-in" list (this method has been chosen to fix bugs easily without having to recompile WinPic).

The parameter names in DEVICES.INI should speak for themselves. Parameters beginning with Cfgmask_ are bitmasks for the configuration word. If the according function does not exist in a particular device, the value should be zero.

Hexadecimal numbers must have the suffix "0x" to tell them from decimal numbers.

WinPic can produce a dumpfile with the definitions of all built-in PIC device definitions (in the old versions of WinPic, the device definitions were all "built-in" so I had to modify the C sourcecode and recompile WinPic whenever a new PIC appeared. Hopefully this is over now... but if there is a new programming algorithm for a new PIC device, you still have to wait for a new release of WxPic). To produce a dumpfile with the built-in device definitions, select Tools / Specials / Dump built-in device list to file from WxPic's main menu.

### HautProgam Algorithm

The programming algorithm used for a particular device is stated in DEVICES.INI like this (for example in the 16F628):

EraseAlgo=16Fxx
CodeProgAlgo=16Fxx
ConfigProgAlgo=CONFIG_MEM_16xxx
DataProgAlgo=DATA_EEPROM_16xxx

(other parameters in DEVICES.INI are explained in the next chapter)

As you see, different algorithms can be used to erase / program CODE / program CONFIG MEMORY / program DATA MEMORY . A lot of examples can be found in the file dumpfile of the built-in device definitions.

Due to Microchip diligently writing new "Flash Memory Programming Specifications" for every new family of chips they made, the following 'algorithm names' existed by the time of this writing. (In the meantime, there will be many more - just look into the file DEVICES.INI) :

16Fxx
  for 16F84, 16F628, and many similar devices.
16Fxx_OLD_ERASE
  The 16Fxx algorithm has been fixed in V1.2. In case it would bring a major regression, this algoritm is the old (pre-V1.2) 16Fxx algorithm
12Fxx
  for 12F629 and 12F675 (note that 12Fxx and 16Fxx are identical and use the CanRead indicator to adapt to different PIC capabilities)
16F7x7
  for 16F737 and others. Programs two memory locations at a time. New since August 2004 !
16F81x
  for 16F818 and others. Programs four memory locations at a time. In the 16F818 used for code programming, not sure if this applies to the data EEPROM as well (old programming spec was unclear).
16F87x
  for 16F870 and other NON-"A" types. Programs one memory location at a time. The "erase-all" algorithm also differs from other devices !
16F87xA
  for 16F877A and other -A types. Programs eight memory locations at a time.
  Caution: The programming algorithm for the -A devices is totally different from their older "non -A" devices !
PIC18F
  for all members of the PIC18Fxxx(x) family. For these devices, the size of the so-called "write buffer" should be specified too, like this:
  CodeMemWriteLatchSize=64 ; Write-Buffer-Size in bytes.
CONFIG_MEM_16xxx
  configuration memory programming algorithms for 16F84, 16F628 and others "early devices with FLASH memory"
DATA_EEPROM_16xxx
  data EEPROM programming algorithm for many (but not all) PICs with on-chip data EEPROM memory.
MULTI_WORD (added in V1.2)
  This algorithm programs a row at once. The number of words in the row has to be defined in the CodeMemWriteLatchSize parameter. If this algo is used for data the size of the row must be defined in parameter CodeMemEraseLatchSize.

Haut

### Erase Algorithm

Special ERASE algorithms (in DEVICES.INI) :

ERASE_16F62xA
ERASE_16F81x
ERASE_16F87xA
ERASE_16F87x
ERASE_12F6xx
PIC18F (usable as parameter for ERASE_ALGO)
PIC18F_OLD (added to avoid trouble with "old" and "new" programming specifications)
  One fine day, Microchip changed the 'chip erase pattern' in their "Flash Memory Programming Specification" for some PIC18Fxxxx from 0x0F0F 0x8787 to 0x3F3F 0x8F8F (the latter was found in document DS39622J on page 14). Some newer chips refused to erase with the older algorithm. The question is now, will OLDER chips which *did* work with the original code (based on Microchip's document DS39622B) still work with the NEWER algorithm ? For this reason, the "EraseAlgo" value in WinPic's DEVICES.INI can now be set to either `PIC18F` or `PIC18F_OLD.` For example, a PIC18F2550 could successfully be erased with both command patterns (the one from DS39622B *and* from DS39622J), while a PIC18F8490 could only be erased with the pattern specified in DS39622J.

Device definitions in DEVICES.INI will override the built-in definition table. So, if you find there is a bug in a device definition, add it into DEVICES.INI to let WinPic ignore its internal PIC device table. A message will be displayed in the status line and in WinPic's "Message" list.

Haut

## Parameters in DEVICES.INI

For every PIC device in the definition file, a lot of different parameters can be defined. Usually most of these parameters have the same values as for other PICs of the same family, but some won't. When adding support for a new device, try to find a similar device, copy & paste the definitions to a new segment in the INI file. So you only have to edit a few values - but be careful to find the differences !

The following parameter values (after the '=' character) are taken as an example from the PIC12F675.

DeviceName=PIC12F675
  This string will be displayed in WinPic's device list
CodeMemType=1
  Defines the type of the code (alias "program") memory. '1' means FLASH memory.
CodeMemSize=1024
  Size of the code memory in WORDS. Remember that a PIC-"word" is usually not 16, but 14 bits wide.
DataEEPROMSize=128
  Size of the (data-)EEPROM memory in BYTES.
InternalRAMSize=64
  Size of the internal RAM. Displayed on WinPic's device tab for the user's information, but not really important for programming.
AddrConfigMem=0x2000
  Address of the first location in the PIC's "config" memory. I never found anything different from 0x2000 but who knows...
AddrConfigWord=0x2007
  Address of the PIC's (first!) "configuration word". This usually contains the oscillator configuration, etc etc. The meaning of the bits in the config word is defined in various Cfgmask_xxxx parameters.
AddrDataMem=0x2100
  Start address of the EEPROM data. This is not a real address inside the PIC, but a convention how EEPROM data are embedded in a HEX file, so it's very unlikely to change in future devices (but who knows..)
AddrOscCalib=0x03FF
  Address of the oscillator calibration word. Only exists for a few new devices. A value of 0xFFFFFFFF (i.e. "-1") means "there is no osc calib word in code memory for this device".
ConfigMemUsedLocs00_1F=0x00CF
  New since 2004-08. Defines which of the configuration memory locations do really exist for this device. For each of the first 32 locations in config memory (addresses 0x2000..0x201F), there is a bit in this parameter (bit 0 for address 0x2000, bit 1 for address 0x2001, etc). A ZERO-bit means "this location does not exist. The definition `ConfigMemUsedLocs00_1F=0x00CF` means, only the addresses 0x2000...0x2003 (=ID locations), 0x2006 (processor ID), and 0x2007 (configuration word) exist, all other locations are "unused" or "reserved" (Microchip slang). Some new devices like the 16F737 have more cells in the configuration memory, for example a second configuration word, or a "calibration word", etc.
ConfigMemUsedLocs20_3F=0x0000
  New since 2004-08. Defines which of the 'upper' configuration memory locations (address range 0x2020..0x203F) do really exist. In August 2004, no such device was known to the author but you never know - the programming specs always mention the configuration memory area 0x2000...0x203F so there may be something here in future.
DeviceIdAddr=0x2006
  Address of the device ID location. Note that some early PIC micros did not have ID locations !
DeviceIdMask=0x3FE0
  A mask for the processor ID inside the device ID location. Zero-bits are masked out, when comparing the value read from the PIC with the value from the 'DeviceIdValue' parameter. Why this ? Some PICs have coded the revision step number in some of the device ID bits, which must be stripped when detecting the chip type.
DeviceIdValue=0x0FC0
  Indicates the processor type. Note that some early chips like the once-popular PIC16F84 did not identify themselves through the device ID ! This value is read from the PIC; and WinPic searches for this value in the device database.
CanRead=0
  A 'flag' for the programming algorithm. "CanRead=0" means the PIC cannot be read while programming, so it must be verified after programming. Taking a look into the PIC's programming specification to find the right value. For newer PICs with "more than one WORD per programming cycle" it seems to be impossible to verify while programming, so CanRead must be zero.
EraseAlgo=12Fxx
  Defines which algorithm must be use to erase the code memory in this chip. Some algorithm symbols are listed in the previous chapter.
CodeProgAlgo=12Fxx
  Defines which algorithm must be used to write the code ("program") memory in this device. Note that Microchip seem to be very busy as far as implementing new, incompatible programming algorithms for new devices - which can be a real pain for authors of PIC programming software !
CodeMemWriteLatchSize=64
  Defines the size of the "write-buffer" for PIC18Fxxxx. For most(?) 16F's, this parameter is not required (question mark because this *may* change in future). Consult the "Flash memory programming specification" of the device which you want to support to find this value.
ConfigProgAlgo=CONFIG_MEM_16xxx
  Defines which algorithm must be used to write the configuration memory in this device. Note that the config memory programming algorithm is very different from the code memory programming algorithm, especially for newer chips. The conig mem prog algo seems to be changed less frequently by Microchip than the code mem algorithm.
DataProgAlgo=DATA_EEPROM_16xxx
  Specifies the DATA EEPROM programming algorithm. Fortunately this changes less frequently than the code memory programming algorithm. Up to now, there is only one DATA EEPROM prog'ing algorithm (DATA_EEPROM_16xxx) which even works for the 12Fxxx family.
Ti_Clock_us=5
  The mininum time for a serial clock pulse. Usually 5 microseconds. Due to the complexity of direct port access under windows, WinPic can hardly realize this with the "extra simple" programmers. But specifying the correct value from the PIC's datasheet here doen't hurt !
Ti_Prog_us=10000
  The required duration of a "programming cycle", specified in microseconds. If you don't know this exactly, enter 10000 here. A higher value than stated in the PIC programming specification does not hurt for FLASH-based PIC's.
Ti_Erase_us=10000
  The required delay time for the "Erase" command (in microseconds). Usually somewhere around 10 milliseconds.
CmdLoadConfig=0
  The serial command for "Load Config". It is quite unlikely that the bit pattern for this command will ever change, but ... (you guessed it: "who knows").
CmdLoadProg=2
  Serial command for "Load Program". Look into the PIC's programming specification. Quite unlikely to change.
CmdReadProg=4
  Serial command for "Read Program". See comments above.
CmdIncrAddr=6
  Serial command for "Increment address".
CmdBeginProg=8
  Serial command for "Begin Programming". Beware, there are different flavours of this command. Look into the programming spec !
CmdEndProg=14
  Serial command for "End Programming".
CmdLoadData=3
  Serial command for "Load data for EEPROM memory".
CmdReadData=5
  Serial command for "Read data from EEPROM memory"
CmdEraseProg=9
  Serial command for "Erase" or "Begin Erase Cycle". Some programming algorithms ignore this parameter because they use totally different erase method, which must consider the state of the protection bits, etc etc.
CmdEraseData=11
  Serial command for "Erase Data EEPROM".
CmdEraseChip=-1
  Serial command for "Erase Chip" (which, for some devices, only works if the chip is PROTECTED !!!). A value of "-1" means "there is no chip erase command for this PIC".
CmdBeginProgNoErase=-1
  Serial command for "Begin Programming without erase". Don't ask me why they introduced this. Only used by a few code memory programming algorithms.
Cfgmask_unused=0x0E00
  A bitcombination for the configuration word which contains all "unused" bits (bits which do not have a function, and must not be considered when verifying the PIC).
Cfgmask_unknown=0x0000
  A bitcombination for the configuration word which contains all bits which are not covered by any of the following masks, but must be programmable, and must be considered during verify. Reason for this mask: It happened too often that Microchip came up with new devices which had "completely new" functions in the configuration word (see the long list below). If this happens again in future, you still have the chance to edit those bits in the config word in hexadecimal form on WinPic "device/config" tab.
Cfgmask_cpbits=0x0080
  Bitmask for the code protection bits. There may be more than one CP bit, sometimes for different areas in the code memory, but since WinPic was never intended for mass production I do not want to support all these different kinds of code protection. When setting the "code protection" checkmark on the device/config tab, all these CP bits are activated, if code protection is turned off, all CP bits are set to one because they seem to be "low-active", at least for all devices I know. It Microchip decides to change this one bad day, like they did with the "PWRTE" bit. In that case you may find an "inversion mask for the code protection bits" in a future release of WinPic... or you will find the note "sorry I don't support that nonsense").
Cfgmask_cpd=0x0100
  Bitmask for the data protection bit (as far as I know there is only one such bit, if any, but there may be more.... who knows ;-)
Cfgmask_pwrte=0x0010
  Bitmask for the PWRTE bit (power-on-timer-enable). This bit has different names, depending into which datasheet you look...
Cfgmask_inv_pwrte=0x0010
  Bitmask to INVERT the "pwrte" bit. I can only guess why Microchip did change the polarity of this bit... now its up to you to look into the PIC's datasheet to find out if this bit is inverted or not. As far as I remember, they changed the polarity when replacing the good old 16C84 with the 16F84 but I am not really sure. If the PWRTE bit is inverted ("low-active"), this parameter must have the same value as `Cfgmask_pwrte`.
Cfgmask_wdte=0x0008
  Bitmask for the watchdog timer enable bit in the configuration word.
Cfgmask_oscillator=0x0007
  Bitmask for the ocillator selection. The possible values of these bits are defined by the following parameters. Some PICs have four, some have eight possible combinations:
  Cfgmask_osc_rc=0x0007
  Cfgmask_osc_hs=0x0002
  Cfgmask_osc_xt=0x0001
  Cfgmask_osc_lp=0x0000
  Cfgmask_osc_extclk=0x0003
  Cfgmask_osc_intrc_noclkout=0x0004
  Cfgmask_osc_intrc_clkout=0x0005
  Cfgmask_osc_extrc_noclkout=0x0006
Cfgmask_lvp=0x0000
  Configuration bit for "low voltage programming". A value of 0x0000 means that there is no low-voltage programming option for this device.
Cfgmask_boden=0x0040
  Bitmask for "brown-out detection".
Cfgmask_mclre=0x0020
  Bitmask for "MCLR enable". Some (newer) PICs allow using the MCLR pin ("reset input") to be used as "I/O" pin (often only an input pin, see datasheet).
Cfgmask_ddebug=0x0000
  Bitmask for the "debug" function in some devices. See datasheet. Never used, never tested.
Cfgmask_wrcode=0x0000
  Bitmask to enable the "write to code memory" function. Yes, some PICs allow programming the code memory during run-time which can be used to write a custom "bootloader" through a standard serial interface. Hardly used as far as I know, at least for PICs.
Cfgmask_bandgap=0x3000
  Bitmask for the bandgap calibration bits. A value of 0x0000 means "there are no bandgap calibration bits in this device".
Cfgmask2_used_bits=0x0000
  If there is a second configuration word in the PIC, all existing bits must be set in this value. If a second word exists at all, only a few bits really exist in it. Because this is so rarely used there is no "decoder" for the second config word in WinPic. You can only enter the bits for the 2nd config word in hexadecimal form. WinPic only needs this bitmask to verify the 2nd config word properly because unimplemented bits may read "zero" or "one" - so they must not be ignored during verify. Cfgmask2_used_bits=0x0000 means "there is no second config word".
  Please note: If there is a second configuration word, bit 8 in the parameter `ConfigMemUsedLocs00_1F` should be set - otherwise WinPic may consider this location as "unused".

Haut

Author: Wolfgang Buescher (DL4YHF)
Modified by: Philippe Chevrier