---------------------------------
   IDA to SoftIce symbol loader
   version: 0.03c release
---------------------------------

1)Author words
2)How to use
3)Problems
4)History
5)Utilities (for other file types -> map2sice)

--------------------------------------------------------------------------------------------------------------------------
Author: Mostek
home page: http://mostek.subcultural.com

mail:      mostekaccess@lycos.com

Authors requests:

1st
If you don't like or you want to add something please write to me.
I would be more than happy to help.

If you find a bug, it would be nice to mail me.

Because my 1st language isn't C/C++, I don't know much about it.
If anything could be done easier I'm waiting for your mail.

2nd
Included in this version:
  Local/Global Variables
  Local/Global Procedures
  Structures/Unions
  Local Labels
  Variables and Code in any Segment
  Renaming of Import Functions (read the problems and history sections (down))
  Register Variables(values, pointers)
  IDA Source Listing

Support for: PE, LE file types

3rd
A Big thanks to : Tsehp, The Owl, Ousir, BlindnAngel, Snacker and Ilfak for helping me out.

--------------------------------------------------------------------------------------------------------------------------
2)How to use

1st
You MUST add next "4"-5 lines to ..IDA\PlugIns\PlugIns.cfg file (in this order exactly),
because plugIn depends on the number of init calls made to i2s:

        Load_PDB_File   pdb              Alt-F12         0   ;This line is just for those that have pdb.plw in IDA\PlugIns dir.
                                                             ;By default it uses Ctrl-F12 and that one we want to have for us.
        I2S_Setup       i2s              0               3
        I2S_Source_Info i2s              Ctrl-F12        2
        I2S_Save_NMS    i2s              Shift-F12       1
        I2S_Conversion  i2s              F12             0

NOTICE:
If some IDA command uses this any of the hot-keys you can change it to something else in idagui.cfg in IDA dir.

2nd
PlugIn must be used under Windows as it uses Windows functions.
Why? 1. NM32.h was set/reversed only for 32bit windows programs.
     2. PlugIn uses windows function fot allocating memory and for loading nms file to softice.

3rd
Read the whole History section as there are the explanations of i2s features and how to use them.
I made it like this because I didn't want to have two similar sections 'History' and 'What is new'.

4th
You can have spaces in your names if you want. PlugIn replaces them with '_'.
SoftIce supports extended ASCII table, so you can use those characters too.

--------------------------------------------------------------------------------------------------------------------------
3)Problems

1st
Sometimes plugIn will report "Align directive (ea:xxxxxxx) isn't allowed to have a name." even
if an Align directive is not there.
This is a bug in IDA, so I can't help (well at least in IDA4.04).
SOLUTION:
Define that byte/word/dword (press 'd') and if you're at it, define a few next ones too.

2nd <-NO FIX
PlugIn only supports EBP based local variable. ESP based local variables will NEVER be implemented.
The variable changes offset in the function and I can't explain SIce when to use one offset and when the other.

3rd
Some primitive types are not right. (octaword, tbyte, packed real)
If anyone knows the primitive type numbers for this types, please let me know.

--------------------------------------------------------------------------------------------------------------------------
4)History (fixed bugs/new things)

 version
 0.03c     -A small bug fixed.
            If command line that wasn't a part of procedure had anterior or posterior lines plugin crashed.

 0.03b     -Lots of things changed to 0.03a version, but some remained.
            So please read both, as some setups set in 0.03a are valid for 0.03b too.

           -IDA 4.10 is not supported any more. Sorry.

           -Now plugIn 'demangles' mangled procedure names.
            How to set: IDA->Options(menu)->Demangled Names...(menu item)->dBox will open ->
                        ->press 'Setup Short Names'-> check 'Inhibit everything except the main name' (it's the 1st option)->
                        ->press 'Ok'
            Everything else can be left the same.
            So you can see the whole demangled definition in IDA and plugIn can get the name only.
            NOTICE:
            I'm not sure if ':' is set as allowed by default in IDA (user names), but SIce can handle it. This means that
            in SIce you can write something like 'u areacb_t::choose_area2' and everything will work as it should.
            If ':' is not allowed you can add ':' to 'NameChars' variable in ida.cfg file(IDA directory).

	   -Completely rewritten IDA listing management.
	    Please read carefully.
	    All those 'SIce can't load big source files' problems solved.

	    -Read 1st part in 'How to use' section in this file. -> set/reset plugIn.cfg.
	     Why?
	     'Source files definition' window took the hot-key of 'Setup window'.
	     You can still access 'Setup window' through 'Source files definition'->
	     ->double click on the first line (you will see what I mean) or by selecting it in 
	     plugIn manu.
	     
	    -In 'Source files definition' you can enable/disable source files that you want/(don't want)
	     in your nms database-> you can drastically lower the size of nms file and
	     needed memory for source files in SIce.
	     If you don't want any source code you can disable source creation in 'Setup Window'.
	     
	     If you will double click on the source file a DialogBox will open with file info.
	     You can change the file name. Default file names are made as: seg%Dfile%D.asm.
	     Notice:
	     Only asm extensions are allowed. So if you will forget to add one plugIn will add it for you.
	     Notice2:
	     File name can be only 31 chars long.

	     Notice:
	     Other options in "Source File Information" DBox aren't written yet,
	     so you will have to wait to next version.

            -Re-notice:
             When saving the database a directory will be created with the name 'databaseName source'.
             All source files will be saved to this directory.
             The first time you will load the database with Loader32 you will be asked where the source is.
             After that everything will work normally.

	    -For those that want compile this plug:
	     In Source\other dir you will find how to change kernel.h in SDK versions 55-58 (IDA 4.16 - 4.20).
	     This was a bug in kernel.h.
	     (Fixed bug from 0.03a --> 'All the optimization MUST be disabled.' )
            
           -Setup window is changed slightly.
            'Always Use Default Values' doesn't save flags to registry any more.
            You have to press 'Set default' button.
	    Reason:
            It complicated things if you just want to change one option in current database.

           -Minor fix to n2t utility->not all 'Source code lines definitions' were shown.

 0.03a     -Internal version.
            Had lots of problems with SoftIce and source loading.
            Only small sources were loaded.

           -Maybe a sad news but I will not support IDA 4.04 any more.
            I have problems with it and more a "public" IDA 4.17 is already on the net.

           -Finally the IDA listing is included in the nms file.
            Comments and other sweet stuff can now be seen in SoftIce. :)
            SoftIce supports extended ASCII table, so you can use those characters too.
            ADVICE:
            SoftIce cuts very long lines so use anterior and posterior lines for your bigger comments.
            And more it's annoying to move the SoftIce source screen left and right all the time.

            NOTICE:
            Only code segments are source listing bearers. All the other segments source is appended to them.
            ex.:
                                                1     2     3     4      5     6     7     8     9    10    11
            segments in IDA (not in program): DATA, DATA, CODE, DATA, IDATA, CODE, DATA, CODE, DATA, CODE, CODE
            You will have 5 source barers -> codeSeg3.asm, codeSeg6.asm, codeSeg8.asm, codeSeg10.asm, codeSeg11.asm
            In  codeSeg3.asm you will have listing from DATA(1), DATA(2), CODE(3), DATA(4), IDATA(5)
            In  codeSeg6.asm you will have listing from CODE(6), DATA(7)
            In  codeSeg8.asm you will have listing from CODE(8), DATA(9)
            In codeSeg10.asm you will have listing from CODE(10)
            In codeSeg11.asm you will have listing from CODE(11)

            This means that every segment listing until first code segment and all until next code segment
            will be in the first code segment listing.
            All other code segments will have only segments listings of those until next code segment.

      !!!!! KNOWN PROBLEM:
            -SoftIce doesn't load larger databases. It looks that SoftIce can't load files with a really big source file.
             It is advisable first to load nms file with Loader32 and if it doesn't fail you can use i2s's direct loading.
             This problem doesn't exist if source listing isn't included (->much, much smaller nms file).
     !!!!!!! NOTICE:
             Before trying to load larger databases SAVE all your work, because sometimes the computer just resets.
            -When saving the database a directory will be created with the name of the database + source.
             All source files will be saved to this directory.
             The first time you will load the database with Loader32 you will have to define where the source is.
             After that everything will work normally.

            -If the plugIn reports "I2S: Can't find the command line. Please read the readme.txt on how to solve this."
             it means that it can't find the collapsed function name -> in IDA go to 'View' menu ->'Setup hidden items'->
             ->uncheck 'Display hidden functions'.
             This options displays hidden function and preserves hidden function attribute. If you want to see those functions
             you will have to un hide it manually.

           -Setup window is now set: -you can select the output directory for nms databases
                                     -enable/disable source :
                                        Enabled  -> IDA source listing will be added to nms file.
                                        Disabled -> Creates nms file without any source listing info.
                                                    This version creates even smaller nms file than previous versions.

                                     -enable/disable default values :
                                        Enable  -> The plugIn will save current path and flags(source included) to registry.
                                                   This info will be used as default values for any new IDA database.
                                        Disable -> The current path and flags will be used with current IDA database only.
                                                   So you can select output directory for every IDA database.
                                                   And set current status on 'include source' flag.

                                     NOTICE:
                                     If you will change the directory when saving the nms file,
                                     the plug will ask if you want to change the output directory
                                     (this directory will be used only with current IDA database and not
                                     as a default value for new IDA databases).
                                     

           -Now you can have a new register name on every instructions in procedure.
            Previously only one register name was allowed for the whole procedure.
            Read in IDA how can you define various names for the same register.
            PROBLEM:
            Without source included, when in SoftIce, you will only see the name of the first register,
            but the names will work.

           -If you get a warning =>"Can't rename byte at xxxx as 'sub_XXXXX_XXXXXXX' because the name has reserved prefix."
            When you will get back to IDA screen go to that address(read the address in msg window) and change address to:
            ex.: before:  'sub_401656'
                  after:  '_sub_401656' -> Just add an underscore in front of the name and everything will be ok.

           -More a notice than anything else:
            In kernwin.h(IDA SDK) I moved public definition of class linearray_t to the beginning of the class(now everything is public).
            So if you want to compile the plug you will have to fix the linearray_t class definition(IDA SDK).
           -There is a problem when compiling the plug. All the optimization MUST be disabled or the
            plug will crash (read in Problems section above).

            I have tested the speed difference of 2i and 3a version and it's horrifying.
            Well in the end it is better to have a slower plugIn than no plugIn at all.
            
           -A little update to n2t utility.

 0.02i     -Sometimes plugIn will report "IDA returned 0 pointer (ea:%x)...." on a 'Local name'.
            This is a bug in IDA (it doesn't return the pointer to the name).
            Fix:
            It was such a stupid solution that I don't want to talk about.
           -Function register renaming is added.
            Bug:
            If IDA didn't set the register array than the plugIn would crash and take IDA with it.
            Fix:
            Added creation of register array.
           -Now (if you want) the last saving directory is remembered and written to the database(nms files).
           -If you will change the directory of the original file and the plugIn would need it for segment
            definition. You can point to the file and plugIn will update IDAs file path.
           -It supports LE (vxd) files.
            It did before also, but I had to be sure to allow it.

            Other types:
            Unfortunately NE files aren't supported. I can't get SoftIce to set the database to a program.
            It loads it just fine, but it doesn't 'connect' it to a program.
            Maybe it's just my problem, as I'm using a MME driver for a NE file type test program.
            You can try it with yours NE type programs (un comment NE file type line in init() procedure(i2s.cpp) and compile).

            
 0.02h     -Now if file type is not PE, the warning is shown only one time.
            But be careful for this to work you MUST read 'How to use' section of this file.
            If the warning will be shown more than ones, please mail me.
           -No more difference between Win95 and WinNT OS types.
           -Update made to nms32.h .
           -I thrown out 'How to compile' section of this file, as (probably) nobody needs it.
           -Function register renaming is added. But only standard registers are included (from al to edi, no FPU or similar)
            You can use register as value or as pointer to structure.
            If register comment is not present than plugIn will assume that register is a value.
            If register comment is     present than plugIn will assume that register is a pointer to 'structure' -> type defined in comment.
            ex.:
                 Old name = ecx
                 New name = this
                 Comment  = class_SetSoftIce		<-class_SetSoftIce is a structure defined in IDA (be careful case sensitive)
            
            SoftIce shows register name only if register is a value.

            BUT if register is used as a pointer the '?','d',... commands will still work
            (ex.: '?this' will show all variables of class_SetSoftIce structure).
            (ex.: '?this->currentindex' will show the value of currentIndex)
            (ex.:
            struc myStruct2
            {
               dw        var1;
               dw        var2;
            };
            struc myStruc
            {
               dw        var1;
               myStruc2  part2;
            }
            'pMyStruc->part2' will show the values of myStruc2 structure)

            Notice!
            You can use '.' in the place of '->' and it will still work.

           -"If nms file is loaded to SIce with F12 command types are not defined."
            Well loading nms file had nothing to do with it. currentIndex variable wasn't reset.
            So all type indexes were wrong(except the first time you started the plugIn).


 0.02g     -I throw out the request for a '.'(dot) in user-defined name.
           -Sometimes there is a program that has import and some other READ section put together to one segment.
            But IDA will make them separate as import segment and READ section segment.
            This caused that you didn't saw your READ section variables in SIce.
            Now this is fixed. You can have as many segments created from one file segment.

 0.02f     -import names (I forget to set .idata section right, so now it is).
            NOTICE:
            Not all function have jump reference in CODE segment.
            Some call directly -> call[ds:xxxxx] .
            NOTICE2:
            The plugIn looks at import section entrances as variables, so I don't see any use of using them.
            I process them just if some strange program would add a variable somewhere in there.


 0.02e     -segments (failed to do the right thing if:  CODE->DATA->some segments missing in IDA (ex.RSRC)->CODE(or DATA)...)
            In SIce the second CODE(DATA) segment symbols would be set for 'RSRC' segment and not for CODE(DATA) as it should.
           -hash offset table (causing SIce fatal error, when used addr, map32, .. commands)
           -import names (dll exported names in SIce were replaced with function names from IDA import section)
            (solution: file name is appended to function names (ex. 'CloseHandle__myfile_exe' ))
            So you can set breakpoint on the global function(bpx CloseHandle),
            or just on the programs one(bpx j_CloseHandle__myfile_exe).
            1st bpx CloseHandle                -> SIce will break with every program that will try to execute CloseHandle function
            2nd bpx j_CloseHandle__myfile_exe  -> SIce will break only when your program will try to execute CloseHandle function).
           -now function can have 'unlimited'(well you know what I mean) number of lines in it (previously 2000)

 0.02d     -fixed bug reporting errors of structure definition to main loop (causing FATAL ERRORs)

 0.02c     -rewritten segment definition part of the code, now you can have as many segments (with code and data) as you like
           -fixed minor bug with definition of the source file
 
 0.02b     -added one primitive type (probably not the right one, but at least you could load the symbols to SIce)

 0.02      -first release (not perfect, but at least something came out after around 9 month of work(well probably 4-5 month of real work))
           -rewritten some part of segment definition (still not bullet proof)

 0.01      -first internal version (had more problems with segments that I could think of, and some problems with allocating memory)

--------------------------------------------------------------------------------------------------------------------------
5)Utilities

1st (n2t)
For testers there's another utility => n2t.exe

It converts nms file to text file
command line w98  :  n2t  nmsName.nms textName.txt
command line w2000: "n2t" nmsName.nms textName.txt

You can define only 'nmsName.nms' and utility will create nmsName.txt.

You MUST use this command line or it will fail.
Source is included. (I'll not explain what to do to assemble it, source is here just to see what and where.)
(Well in some parts I changed eax<->edi to get even more speed, but because of that the registers eax and edi are kind a
strangely used.)

2nd (map2sice)
This one is intended for other file types (NE,...).
