This repository is a mirror!

copy *.bin ..\*.vcl
del *.bin

; This file contains design-time information for Button controls.
;
; One file may contains description of more than one control.
; Look at 'DesignTimeInfo' macro definition.
;
; This file must be compiled with FASM compiler to get binary
; file. It will be compiled as .COM file. This is not executable
; file. Don't start it.

include '..\..\..\source\designtime.inc'
include 'winconst.inc'


DesignTimeInfo                                     \
                                                   \       ; 1. BUTTON CONTROL
        'BUTTON',                                  \
        'Button control',                          \
        'Standard',                                \
        'Button',                                  \
        WS_VISIBLE or BS_PUSHBUTTON or WS_CHILD,   \       ; default style
        0,                                         \       ; default ex style
        64, 25,                                    \
        <                                          \       ; style names
           BS_ICON,      "Specifies that the button displays an icon",   \
           BS_BITMAP,    "Specifies that the button displays a bitmap",   \
           BS_LEFT,      "Places text on the left of the button",   \
           BS_RIGHT,     "Places text on the right of the button",   \
           BS_CENTER,    "Places text in the center (horizontally) of the button",   \
           BS_TOP,       "Places text on the top of the button",   \
           BS_BOTTOM,    "Places text on the bottom of the button",   \
           BS_VCENTER,   "Places text in the center (vertically) of the button",   \
           BS_MULTILINE, "Allows wrapping of the button's text if necesary",   \
           BS_NOTIFY,    "Enables button to send addictional notification messages",   \
           BS_FLAT,      "Creates flat button"    \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD,                                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $0000000f,                                 \            ; This is SubtypeMask
        <                                          \
          BS_PUSHBUTTON, 'Normal push button',     \
          BS_DEFPUSHBUTTON, 'Default push button'  \
        >,                                         \            ; This is SubtipeRange
        NONE,                                      \            ; Library file NULL, because it's standard component.
        'Button.ico',                              \            ; Image for icon
\
\ ; Checkbox control.
\
        'BUTTON',                                  \
        'Checkbox control',                        \
        'Standard',                                \
        'Checkbox',                                \
        WS_VISIBLE or BS_CHECKBOX or WS_CHILD,     \       ; default style
        $0,                                        \       ; default ex style
        80, 21,                                    \
        <                                          \       ; style names
           BS_LEFTTEXT,  "Places text on the left of the checkbox",   \
           BS_PUSHLIKE,  "Makes checkbox act like the push button",   \
           BS_MULTILINE, "Allows wrapping of the checkbox's text if necesary",   \
           BS_NOTIFY,    "Enables checkbox to send addictional notification messages",   \
           BS_FLAT,      "Creates flat checkbox"    \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD,                                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $0000000f,                                 \            ; This is SubtypeMask
        <                                          \
          BS_CHECKBOX,     'User controled checkbox',    \
          BS_AUTOCHECKBOX, 'Auto checked checkbox',      \
          BS_3STATE, '3-state checked checkbox',   \
          BS_AUTO3STATE, 'Auto 3-state checkbox'       \
        >,                                         \            ; This is SubtypeRange
        NONE,                                      \            ; Library file NULL, because it's standard component.
        'CheckBox.ico',                            \            ; Image for the icon.
\
\ ; Radiobutton control.
\
        'BUTTON',                                  \
        'Radiobutton control',                     \
        'Standard',                                \
        'Radiobutton',                             \
        WS_VISIBLE or BS_RADIOBUTTON or WS_CHILD,  \       ; default style
        $0,                                        \       ; default ex style
        80, 21,                                    \
        <                                          \       ; style names
           BS_LEFTTEXT, "Places text on the left of the radiobutton",               \
           BS_PUSHLIKE,  "Makes radiobutton act like the push button",   \
           BS_MULTILINE, "Allows wrapping of the radiobutton's text if necesary",   \
           BS_NOTIFY,    "Enables radiobutton to send addictional notification messages",   \
           BS_FLAT, "Crates flat radiobutton"    \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD,                                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $0000000f,                                 \            ; This is SubtypeMask
        <                                          \
           BS_RADIOBUTTON, 'Standard Radiobutton', \
           BS_AUTORADIOBUTTON, 'Auto Radiobutton'  \
        >,                                         \            ; This is SubtypeRange
        NONE,                                      \            ; Library file NULL, because it's standard component.
        'radiobtn.ico',                            \            ; Image for the icon.
\
\ ; Groupbox control.
\
        'BUTTON',                                  \
        'Group box control',                       \
        'Standard',                                \
        'Group box',                               \
        BS_MULTILINE or WS_VISIBLE or BS_GROUPBOX or WS_CLIPSIBLINGS or WS_CHILD,    \       ; default style
        $00010020,                                 \       ; default ex style
        128, 128,                                  \
        <                                          \       ; style names
           BS_LEFT,      "Places text on the left of the box'es frame",   \
           BS_RIGHT,     "Places text on the right of the box'es frame",   \
           BS_CENTER,    "Places text in the center (horizontally) of the button",   \
           BS_FLAT,      "Creates flat groupbox"    \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD,                                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00010000,                                 \            ; This is StyleExMaskOr
        $0000000f,                                 \            ; This is SubtypeMask
        <BS_GROUPBOX, 'Regular group box'>,        \  ; This is SubtypeRange
        NONE,                                      \            ; Library file NONE, because it's standard component.
        'GroupBox.ico'                                          ; Image for the icon.

include '%finc%/win32/win32a.inc'
include '..\..\..\source\designtime.inc'
;include 'winconst.inc'
;include '..\..\..\source\AsmEdit\AsmEdit.inc'

DesignTimeInfo                                     \
                                                   \       ; 1. TButtonEdit control
        'TButtonEdit',                             \
        'Edit control with button inside',         \
        'Fresh',                                   \
        'Edit',                                    \
        WS_VISIBLE or WS_CHILD or ES_LEFT or ES_AUTOHSCROLL, \      ; default style
        WS_EX_CLIENTEDGE,                                          \       ; default ex style
        121, 21,                                   \
        <                                          \       ; style names
            ES_LEFT        , "Align left",         \
            ES_CENTER      , "Align center",       \
            ES_RIGHT       , "Align right",        \
            ES_UPPERCASE   , "Converts the text into uppercase characters", \
            ES_LOWERCASE   , "Converts the text into lowercase characters", \
            ES_PASSWORD    , "Displays all characters in the edit control as asterisks", \
            ES_NOHIDESEL   , "Specifies that the selected text is not hidden when the edit control loses the keyboard focus", \
            ES_AUTOHSCROLL , "Automatically scrolls text horizontally", \
            ES_OEMCONVERT  , "Ensures the proper conversion of characters", \
            ES_READONLY    , "Makes the edit control read-only", \
            ES_WANTRETURN  , "Inserts a carriage return when the user presses the ENTER key", \
            ES_NUMBER      , "Restricts input to the edit control to digits only"             \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        ES_MULTILINE,                              \            ; This is StyleMaskAnd
        WS_CHILD,                                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $00000000,                                 \            ; This is SubtypeMask
        NONE,                                      \
        NONE,                                      \         ; Library file NULL, because it's standard component.
        'btnedit.ico'

include '%finc%\win32\win32a.inc'
include '..\..\..\source\designtime.inc'


DesignTimeInfo                                                \
                                                              \         ; 1. Control starts here
        'SysTreeView32',                                      \
        'TreeView Control',                                   \
        'Common',                                             \
        'TreeView',                                           \
        WS_VISIBLE or WS_CHILD or WS_BORDER or TVS_HASLINES,  \         ; default style
        WS_EX_CLIENTEDGE,                                     \         ; default ex style
        128, 128,                                             \
        <                                                     \         ; style names
            TVS_HASBUTTONS      ,"Shows a button to the left side of each parent item.", \
            TVS_HASLINES        ,"Enhances the graphic representation of a tree view control's hierarchy by drawing lines that link child items to their parent item.",\
            TVS_LINESATROOT     ,"Draws lines between root and child nodes",             \
            TVS_EDITLABELS      ,"Allows the user to edit the labels of tree view items.",\
            TVS_DISABLEDRAGDROP ,"Disable drag and drop operation.",                     \
            TVS_SHOWSELALWAYS   ,"Causes a selected item to remain selected when the tree view control loses focus.",    \
            TVS_SINGLEEXPAND    ,"Causes a tree view item to be expanded when it becomes selected and to be closed when it becomes unselected.",\
            TVS_CHECKBOXES      ,"Enables check boxes for items in a tree view control.",\
            TVS_DISABLEDRAGDROP ,"Prevents the tree view control from sending TVN_BEGINDRAG notification messages.",\
            TVS_FULLROWSELECT   ,"The entire row of the selected item is highlighted, and clicking anywhere on an item's row will cause it to be selected.",\
            TVS_INFOTIP         ,"The tree view control will send the TVN_GETINFOTIP notification to obtain tooltip information.",\
            TVS_NOHSCROLL       ,"Disables horizontal scrolling in the control.",\
            TVS_NONEVENHEIGHT   ,"The height of the items can be set to an odd height with the TVM_SETITEMHEIGHT message.",\
            TVS_NOSCROLL        ,"Disables both horizontal and vertical scrolling in the control.",\
            TVS_NOTOOLTIPS      ,"The tree view control does not support tooltips.",\
            TVS_RTLREADING      ,"Normal windows display text left-to-right (LTR).",\
            TVS_TRACKSELECT     ,"Enables hot tracking in a tree view control." \
        >,                                                    \
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD ,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $0       ,                                            \         ; This is SubtypeMask
        NONE,                                                 \
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'treeview.ico',                                       \
                                                              \         ; 1. Control starts here
        'SysListView32',                                      \
        'ListView Control',                                   \
        'Common',                                             \
        'ListView',                                           \
        WS_CHILD or LVS_REPORT or LVS_EDITLABELS,             \         ; default style
        WS_EX_CLIENTEDGE,                                     \         ; default ex style
        128, 128,                                             \
        <                                                     \         ; style names
            LVS_SINGLESEL        ,".",\
            LVS_SHOWSELALWAYS    ,".",\
            LVS_SORTASCENDING    ,".",\
            LVS_SORTDESCENDING   ,".",\
            LVS_SHAREIMAGELISTS  ,".",\
            LVS_NOLABELWRAP      ,".",\
            LVS_AUTOARRANGE      ,".",\
            LVS_EDITLABELS       ,".",\
            LVS_OWNERDATA        ,".",\
            LVS_NOSCROLL         ,".",\
            LVS_ALIGNTOP         ,"Align icons on top.",\
            LVS_ALIGNLEFT        ,"Align icons on left.",\
            LVS_OWNERDRAWFIXED   ,".",\
            LVS_NOCOLUMNHEADER   ,".",\
            LVS_NOSORTHEADER     ,"." \
       >,                                                    \
       <    LVS_EX_GRIDLINES        , "." ,\ ; style Ex names
            LVS_EX_SUBITEMIMAGES    , "." ,\
            LVS_EX_CHECKBOXES       , "." ,\
            LVS_EX_TRACKSELECT      , "." ,\
            LVS_EX_HEADERDRAGDROP   , "." ,\
            LVS_EX_FULLROWSELECT    , "." ,\
            LVS_EX_ONECLICKACTIVATE , "." ,\
            LVS_EX_TWOCLICKACTIVATE , "." ,\
            LVS_EX_FLATSB           , "." ,\
            LVS_EX_REGIONAL         , "." ,\
            LVS_EX_INFOTIP          , "." ,\
            LVS_EX_UNDERLINEHOT     , "." ,\
            LVS_EX_UNDERLINECOLD    , "." ,\
            LVS_EX_MULTIWORKAREAS   , "." ,\
            LVS_EX_LABELTIP         , "." ,\
            LVS_EX_BORDERSELECT     , "." \
        >,                                                    \
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD or WS_VISIBLE,                               \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $3       ,                                            \         ; This is SubtypeMask
        <                                                     \
          LVS_ICON             ,"Each item appears as a full-sized icon with a label below it.",\
          LVS_REPORT           ,"Each item appears on its own line with information arranged in columns. The leftmost column is always left justified, and contains the small icon and label.",\
          LVS_SMALLICON        ,"Each item appears as a small icon with the label to the right of it.",\
          LVS_LIST             ,"Each item appears as a small icon with a label to the right of it. Items are arranged in columns and cannot be dragged to any arbitrary location by the user." \
        >,                                                    \         ; This is SubtipeRange
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'listview.ico',\
                                                              \         ; 1. Control starts here
        'SysMonthCal32',                                      \
        'MonthView Control',                                  \
        'Common',                                             \
        'MonthView',                                          \
        WS_VISIBLE or WS_CHILD or WS_BORDER,                  \         ; default style
        0,                                                    \         ; default ex style
        128, 128,                                             \
        <                                                     \         ; style names
          MCS_MULTISELECT     ,"Allow the user to select a range of days.",\
          MCS_WEEKNUMBERS     ,"Displays week numbers at the left side of each month.",\
          MCS_NOTODAY         ,"The control no longer circles the current day.",\
          MCS_DAYSTATE        ,"The control highlights specific dates by displaying them in bold."\
        >,                                                    \
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD or WS_VISIBLE,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $0       ,                                            \         ; This is SubtypeMask
        NONE,                                                 \
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'monthview.ico',\
                                                              \         ; 1. Control starts here
        'ToolbarWindow32',                                    \
        'Toolbar Control',                                    \
        'Common',                                             \
        'Toolbar',                                            \
        WS_CHILD or TBSTYLE_TOOLTIPS or CCS_ADJUSTABLE,       \         ; default style
        0,                                                    \         ; default ex style
        128, 128,                                             \
        <                                                     \         ; style names
          TBSTYLE_TOOLTIPS,   "The toolbar creates and manages a tooltip control.", \
          TBSTYLE_ALTDRAG,    'Allows the user to change the position of a toolbar button by dragging it while holding down the ALT key.',     \
          TBSTYLE_WRAPABLE,   'Creates a toolbar that can have multiple lines of buttons.'  \
        >,                                                    \
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD ,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $0       ,                                            \         ; This is SubtypeMask
        NONE,                                                 \
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'toolbar.ico',\
                                                              \         ; 1. Control starts here
        'msctls_statusbar32',                                 \
        'Status Bar Control',                                 \
        'Common',                                             \
        'Status',                                             \
        WS_CHILD,                                             \         ; default style
        0,                                                    \         ; default ex style
        128, 128,                                             \
        NONE,                                                 \         ; style names
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD ,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $0       ,                                            \         ; This is SubtypeMask
        NONE,                                                 \
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'statusbar.ico',                                      \
                                                              \         ; 1. Control starts here
        'SysTabControl32',                                    \
        'Tab Control',                                        \
        'Common',                                             \
        'Tab',                                                \
        WS_CHILD,                                             \         ; default style
        0,                                                    \         ; default ex style
        128, 128,                                             \
        <                                                     \         ; style names
           TCS_SCROLLOPPOSITE, ".",                           \
           TCS_RIGHT,          ".",                           \
           TCS_FORCEICONLEFT,  ".",                           \
           TCS_FORCELABELLEFT, ".",                           \
           TCS_HOTTRACK,       ".",                           \
           TCS_VERTICAL,       '.',                           \
           TCS_BUTTONS,        '.',                           \
           TCS_MULTILINE,      '.',                           \
           TCS_FIXEDWIDTH,     '.',                           \
           TCS_RAGGEDRIGHT,    '.',                           \
           TCS_FOCUSONBUTTONDOWN, '.',                        \
           TCS_OWNERDRAWFIXED, '.',                           \
           TCS_TOOLTIPS,       '.',                           \
           TCS_FOCUSNEVER,     '.'                            \
        >,                                                    \
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD ,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $0       ,                                            \         ; This is SubtypeMask
        NONE,                                                 \
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'tabctl.ico',                                         \
                                                              \         ; 1. Control starts here
        'msctls_trackbar32',                                  \
        'Slider Control',                                     \
        'Common',                                             \
        'Slider',                                             \
        WS_CHILD,                                             \         ; default style
        0,                                                    \         ; default ex style
        128, 128,                                             \
        <                                                     \         ; style names
           0    ,"." \
        >,                                                    \
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD ,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $1f      ,                                            \         ; This is SubtypeMask
        NONE,                                                 \
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'slider.ico',                                         \
\
\
        'msctls_progress32',                                  \
        'Progressbar Control',                                \
        'Common',                                             \
        'Progressbar',                                        \
        WS_CHILD,                                             \         ; default style
        0,                                                    \         ; default ex style
        192, 19,                                              \
        <                                                     \         ; style names
           PBS_SMOOTH    ,"PBS_SMOOTH",                       \
           PBS_VERTICAL,  "PBS_VERTICAL"                      \
        >,                                                    \
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD ,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $0       ,                                            \         ; This is SubtypeMask
        NONE,                                                 \
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'progress.ico'

include '..\..\..\source\designtime.inc'
include 'winconst.inc'


DesignTimeInfo                                     \
                                                   \       ; 1. Edit control
        'EDIT',                                    \
        'Edit control',                            \
        'Standard',                                \
        'Edit',                                    \
        WS_VISIBLE or WS_CHILD or ES_LEFT or ES_AUTOHSCROLL, \      ; default style
        WS_EX_CLIENTEDGE,                                          \       ; default ex style
        121, 21,                                   \
        <                                          \       ; style names
            ES_LEFT        , "Align left", \
            ES_CENTER      , "Align center", \
            ES_RIGHT       , "Align right", \
            ES_UPPERCASE   , "Converts the text into uppercase characters", \
            ES_LOWERCASE   , "Converts the text into lowercase characters", \
            ES_PASSWORD    , "Displays all characters in the edit control as asterisks", \
            ES_NOHIDESEL   , "Specifies that the selected text is not hidden when the edit control loses the keyboard focus", \
            ES_AUTOHSCROLL , "Automatically scrolls text horizontally", \
            ES_OEMCONVERT  , "Ensures the proper conversion of characters", \
            ES_READONLY    , "Makes the edit control read-only", \
            ES_WANTRETURN  , "Inserts a carriage return when the user presses the ENTER key", \
            ES_NUMBER      , "Restricts input to the edit control to digits only" \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        ES_MULTILINE,                              \            ; This is StyleMaskAnd
        WS_CHILD,                                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $00000000,                                 \            ; This is SubtypeMask
        NONE,                                      \
        NONE,                                      \         ; Library file NULL, because it's standard component.
        'Edit.ico',                                \         ; Image for icon
        \ ; 2.Textbox control (edit with style es_multiline)
        'EDIT',                                    \
        'Textbox control',                            \
        'Standard',                                \
        'Textbox',                                    \
        WS_VISIBLE or WS_CHILD or ES_LEFT or ES_MULTILINE or ES_AUTOHSCROLL or ES_AUTOVSCROLL, \       ; default style
        WS_EX_CLIENTEDGE,                                          \       ; default ex style
        128, 128,                                  \
        <                                          \       ; style names
            ES_LEFT        , "Align left", \
            ES_CENTER      , "Align center", \
            ES_RIGHT       , "Align right", \
            ES_UPPERCASE   , "Converts the text into uppercase characters", \
            ES_LOWERCASE   , "Converts the text into lowercase characters", \
            ES_PASSWORD    , "Displays all characters in the textbox control as asterisks", \
            ES_NOHIDESEL   , "Specifies that the selected text is not hidden when the textbox control loses the keyboard focus", \
            ES_AUTOHSCROLL , "Automatically scrolls text horizontally", \
            ES_AUTOVSCROLL , "Automatically scroll text vertically", \
            ES_OEMCONVERT  , "Ensures the proper conversion of characters", \
            ES_READONLY    , "Makes the textbox control read-only", \
            ES_WANTRETURN  , "Inserts a carriage return when the user presses the ENTER key", \
            ES_NUMBER      , "Restricts input to the textbox control to digits only" \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD or ES_MULTILINE,                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $00000000,                                 \            ; This is SubtypeMask
        NONE,                                      \
        NONE,                                      \         ; Library file NULL, because it's standard component.
        'Textbox.ico'

; This file contains design-time information for TForm control.
;
; This file must be compiled with FASM compiler to get binary
; file. It will be compiled as .COM file. This is not executable
; file. Don't start it.

include '..\..\..\source\designtime.inc'
include '..\win32\win32a.inc'


DesignTimeInfo					   \
						   \	   ; 1. TForm control
	'TForm',				   \
	'Form control', 			   \
	'Standard',				   \
	'Form', 				   \
	WS_VISIBLE or WS_BORDER or WS_CHILD,	   \	   ; default style
	$00010000,				   \	   ; default ex style
	128, 64,				   \
	NONE,					   \	   ; style names
	NONE,					   \	   ; style Ex names
\
	$00000000,				   \		; This is StyleMaskAnd
	$00000000,				   \		; This is StyleMaskOr
	$00000000,				   \		; This is StyleExMaskAnd
	$00010000,				   \		; This is StyleExMaskOr
	$00000000,				   \		; This is SubtypeMask
	NONE,					   \		; This is SubtipeRange
	NONE,					   \		; Library file NULL, because it's standard component.
	'form.ico'						; Image for icon

include '..\..\..\source\designtime.inc'
include 'winconst.inc'


DesignTimeInfo                                     \
                                                   \
        'LISTBOX',                                 \
        'Listbox control',                         \
        'Standard',                                \
        'Listbox',                                 \
        WS_CHILD+WS_VISIBLE+WS_BORDER,             \       ; default style
        WS_EX_CLIENTEDGE,                          \       ; default ex style
        128, 128,                                  \
        <                                          \       ; style names
            LBS_DISABLENOSCROLL,   'Shows a disabled scrollbar if the listbox doesn''t contain enough items to scroll', \
            LBS_EXTENDEDSEL,       'Allows multiple items to be selected using the SHIFT key', \
            LBS_HASSTRINGS,        'Specifies that the listbox contains string items',\
            LBS_MULTICOLUMN,       'Specifies a multicolumn listbox',\
            LBS_MULTIPLESEL,       'Turns selection on and off when user clicks an item of the listbox',\
            LBS_NOINTEGRALHEIGHT,  'Specifies that height of the listbox isn''t automatically fixed',\
            LBS_NOREDRAW,          'Makes listbox''s appearance not update when changes are made',\
            LBS_NOSEL,             'Prevents user from selecting any items of the listbox',\
            LBS_NOTIFY,            'Makes the listbox send a notification when user double clicks any item',\
            LBS_OWNERDRAWFIXED,    'Specifies that the listbox''s owner is responsible for drawing items, and that they are the same height',\
            LBS_OWNERDRAWVARIABLE, 'Specifies that the listbox''s owner is responsible for drawing items, and that they are different in height', \
            LBS_SORT,              'Makes listbox sort items alphabetically',\
            LBS_USETABSTOPS,       'Makes listbox expand tabs in strings',\
            LBS_WANTKEYBOARDINPUT, 'Makes listbox send WM_VKEYTOITEM message when the key is pressed and the listbox has an input focus'\
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD,                                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $00000000,                                 \            ; This is SubtypeMask
        NONE,                                      \
        NONE,                                      \            ; Library file NULL, because it's standard component.
        'listbox.ico',                             \            ; Image for icon
\
\  ; ComboBox class
\
        'COMBOBOX',                                \
        'Combobox control',                        \
        'Standard',                                \
        'Combobox',                                \
        WS_CHILD+WS_VISIBLE+CBS_DROPDOWN,          \       ; default style
        0,                                         \       ; default ex style
        128, 25,                                   \
        <                                          \       ; style names
            CBS_AUTOHSCROLL,       'Automatically scrolls text in edit when user types something at the end of the line', \
            CBS_DISABLENOSCROLL,   'Displays disabled scrollbar when list doesn''t contain enough items to scroll', \
            CBS_HASSTRINGS,        'Specifies that owner-drawn combobox contains string items', \
            CBS_LOWERCASE,         'Converts to lowercase all texts in combobx', \
            CBS_UPPERCASE,         'Converts to uppercase all texts in combobx', \
            CBS_NOINTEGRALHEIGHT,  'Specifies that height of the combobox isn''t automatically fixed', \
            CBS_OEMCONVERT,        'Converts text in edit control to the OEM character set', \
            CBS_OWNERDRAWFIXED,    'Specifies that the combobox''s owner is responsible for drawing items, and that they are the same height', \
            CBS_OWNERDRAWVARIABLE, 'Specifies that the combobox''s owner is responsible for drawing items, and that they are different in height', \
            CBS_SORT,              'Makes combobox sort items alphabetically' \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD,                                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $00000003,                                 \            ; This is SubtypeMask
        <                                          \
          CBS_DROPDOWN,     'Dropdown combobox',  \
          CBS_DROPDOWNLIST, 'Dropdown listbox',   \
          CBS_SIMPLE,       'Simple combobox'     \
        >,                                         \            ; This is SubtipeRange
        NONE,                                      \            ; Library file NULL, because it's standard component.
        'combobox.ico'                                          ; Image for icon

include '..\..\..\source\designtime.inc'
include 'winconst.inc'


DesignTimeInfo                                                \
        'STATIC',                                             \
        'Label control',                                      \
        'Standard',                                           \
        'Label',                                              \
        WS_VISIBLE or WS_CHILD,                               \         ; default style
        0,                                                    \         ; default ex style
        32, 13,                                               \
        <                                                     \         ; style names
            SS_SUNKEN            , "Draws a half-sunken border around a static control",                                        \
            SS_CENTERIMAGE       , "Centers the image",                                                                                                                            \
            SS_REALSIZEIMAGE     , "Prevents a static icon or bitmap control from being resized as it is loaded or drawn",                                                         \
            SS_RIGHTJUST         , "Specifies that the lower right corner of a static control with the SS_BITMAP or SS_ICON style is to remain fixed when the control is resized", \
            SS_NOPREFIX          , "Prevents interpretation of any ampersand (&) characters in the control's text as accelerator prefix characters",\
            SS_NOTIFY            , "Sends the parent window notification messages when the user clicks or double-clicks the control"          \
        >,                                                    \
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD ,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $1f      ,                                            \         ; This is SubtypeMask
        <                                                     \
            SS_LEFT              , "Left aligned with wordwrap",      \
            SS_CENTER            , "Centered",                        \
            SS_RIGHT             , "Right-aligned",                   \
            SS_SIMPLE            , "Simple one line text",            \
            SS_LEFTNOWORDWRAP    , "Left-aligned without wordwrap"   \
        >,                                                    \         ; This is SubtipeRange
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'label.ico',                                          \         ; Image for icon
                                                              \         ; 2.Shape control starts here
        'STATIC',                                             \
        'Shape control',                                      \
        'Standard',                                           \
        'Shape',                                              \
        WS_VISIBLE or WS_CHILD or SS_ETCHEDFRAME,             \         ; default style
        0,                                                    \         ; default ex style
        128, 128,                                             \
        <                                                     \         ; style names
            SS_SUNKEN            , "Draws a half-sunken border around a static control",                                        \
            SS_CENTERIMAGE       , "Centers the image",                                                                                                                            \
            SS_REALSIZEIMAGE     , "Prevents a static icon or bitmap control from being resized as it is loaded or drawn",                                                         \
            SS_RIGHTJUST         , "Specifies that the lower right corner of a static control with the SS_BITMAP or SS_ICON style is to remain fixed when the control is resized", \
            SS_NOPREFIX          , "Prevents interpretation of any ampersand (&) characters in the control's text as accelerator prefix characters",\
            SS_NOTIFY            , "Sends the parent window notification messages when the user clicks or double-clicks the control"          \
        >,                                                    \
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD ,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $1f      ,                                            \         ; This is SubtypeMask
        <                                                     \
            SS_BLACKFRAME        , "Specifies a box with a frame drawn in the same color as the window frames",                 \
            SS_GRAYFRAME         , "Specifies a box with a frame drawn with the same color as the screen background (desktop)", \
            SS_WHITEFRAME        , "Specifies a box with a frame drawn with the same color as the window background",           \
            SS_ETCHEDHORZ        , "Draws the top and bottom edges of the static control using the EDGE_ETCHED edge style",     \
            SS_ETCHEDVERT        , "Draws the left and right edges of the static control using the EDGE_ETCHED edge style",     \
            SS_ETCHEDFRAME       , "Draws the frame of the static control using the EDGE_ETCHED edge style",                    \
            SS_BLACKRECT         , "Specifies a rectangle filled with the current window frame color",                          \
            SS_GRAYRECT          , "Specifies a rectangle filled with the current screen background color",                     \
            SS_WHITERECT         , "Specifies a rectangle filled with the current window background color"                      \
        >,                                                    \         ; This is SubtipeRange
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'shape.ico',                                          \         ; Image for icon
                                                              \         ; 3.Image control starts here
        'STATIC',                                             \
        'Image control',                                      \
        'Standard',                                           \
        'Image',                                              \
        WS_VISIBLE or WS_CHILD or SS_BITMAP or SS_CENTERIMAGE,\         ; default style
        0,                                                    \         ; default ex style
        128, 128,                                             \
        <                                                     \         ; style names
            SS_SUNKEN            , "Draws a half-sunken border around a static control",                                        \
            SS_CENTERIMAGE       , "Centers the image",                                                                                                                            \
            SS_REALSIZEIMAGE     , "Prevents a static icon or bitmap control from being resized as it is loaded or drawn",                                                         \
            SS_RIGHTJUST         , "Specifies that the lower right corner of a static control with the SS_BITMAP or SS_ICON style is to remain fixed when the control is resized", \
            SS_NOPREFIX          , "Prevents interpretation of any ampersand (&) characters in the control's text as accelerator prefix characters",\
            SS_NOTIFY            , "Sends the parent window notification messages when the user clicks or double-clicks the control"          \
        >,                                                    \
        NONE,                                                 \         ; style Ex names
                                                              \
        $00000000,                                            \         ; This is StyleMaskAnd
        WS_CHILD ,                                            \         ; This is StyleMaskOr
        $00000000,                                            \         ; This is StyleExMaskAnd
        $00000000,                                            \         ; This is StyleExMaskOr
        $1f      ,                                            \         ; This is SubtypeMask
        <                                          \
            SS_BITMAP            , 'Bitmap image'  ,                       \
            SS_ICON              , 'Icon image'    ,                       \
            SS_ENHMETAFILE       , 'Metafile image',                       \
            SS_OWNERDRAW         , 'Owner is responsible for drawing image.',   \
            SS_USERITEM          , 'User defined item'        \
        >,                                                    \         ; This is SubtipeRange
        NONE,                                                 \         ; Library file NULL, because it's standard component.
        'image.ico'

;**********************************************************************
; Fresh project draft file.
; 20.09.2003 John Found
;
; Method for dynamic loading of source-level libraries in design-time
;
; This is example, how Fresh controls executable code will be loaded
; dynamicaly in run time instead of embeding in the source file.
; For every control will be created wrapper DLL, where the main
; functions have standard names:
;
;    RegisterXXXXXClass - registers the window class for the control.
;    XXXXXWinProc       - Window message handler.
;
;  Note that this wrapper includes exactly the same source file
;  as source-level library. The only problem is with global variables
;  used in source-level libs. For this example I define these in
;  .data section, but this is only to allow compilation. The data
;  for these variables is not the same as in the project.
;  This problem requre some solution, before implementation this idea
;  in Fresh.
;**********************************************************************

format PE GUI 4.0 DLL
entry DllEntryPoint

include '%finc%/win32/win32a.inc'
include 'sourcelevel/SizerClass.inc'

;------------------------------------------------------------
; This section is illegal here. But I have no idea how to
; remove it in common case. These variables are globals from
; Fresh project, used in source-level libraries.

section '.data' code readable writeable

hInstance dd ?
hMainWin  dd ?
xGrid     dd ?
yGrid     dd ?
fSnapToGrid dd ?
;------------------------------------------------------------


section '.code' code readable executable

proc DllEntryPoint, hinstDLL,fdwReason,lpvReserved
        enter
        mov     eax,TRUE
        return

; The files from source-level library must be included without
; any change.
include 'sourcelevel\geometry.asm'
include 'sourcelevel\SizerClass.asm'



section '.idata' import data readable writeable

  library kernel32,'KERNEL32.DLL',      \
          user32,'USER32.DLL',          \
          gdi32, 'GDI32.DLL'

  include '%include%\apia\kernel32.inc'
  include '%include%\apia\user32.inc'
  include '%include%\apia\gdi32.inc'

section '.edata' export data readable

  ; functions have to be sorted alphabetically
  export 'SizerClassDTL.DLL',\
         RegisterSizerClass,'RegisterSizerClass',\
         SizerWinProc,'SizerWinProc'

section '.reloc' fixups data discardable

; USER32.DLL constants


; Windows styles

WS_OVERLAPPED	= 000000000h
WS_ICONICPOPUP	= 0C0000000h
WS_POPUP	= 080000000h
WS_CHILD	= 040000000h
WS_MINIMIZE	= 020000000h
WS_VISIBLE	= 010000000h
WS_DISABLED	= 008000000h
WS_CLIPSIBLINGS = 004000000h
WS_CLIPCHILDREN = 002000000h
WS_MAXIMIZE	= 001000000h
WS_CAPTION	= 000C00000h
WS_BORDER	= 000800000h
WS_DLGFRAME	= 000400000h
WS_VSCROLL	= 000200000h
WS_HSCROLL	= 000100000h
WS_SYSMENU	= 000080000h
WS_THICKFRAME	= 000040000h
WS_HREDRAW	= 000020000h
WS_VREDRAW	= 000010000h
WS_GROUP	= 000020000h
WS_TABSTOP	= 000010000h
WS_MINIMIZEBOX	= 000020000h
WS_MAXIMIZEBOX	= 000010000h

; Common Window Styles

WS_OVERLAPPEDWINDOW = WS_OVERLAPPED or WS_CAPTION or WS_SYSMENU or WS_THICKFRAME or WS_MINIMIZEBOX or WS_MAXIMIZEBOX
WS_POPUPWINDOW	    = WS_POPUP or WS_BORDER or WS_SYSMENU
WS_CHILDWINDOW	    = WS_CHILD
WS_TILEDWINDOW	    = WS_OVERLAPPEDWINDOW
WS_TILED	    = WS_OVERLAPPED
WS_ICONIC	    = WS_MINIMIZE
WS_SIZEBOX	    = WS_THICKFRAME

; Extended Window Styles

WS_EX_DLGMODALFRAME    = 00001h
WS_EX_DRAGOBJECT       = 00002h
WS_EX_NOPARENTNOTIFY   = 00004h
WS_EX_TOPMOST	       = 00008h
WS_EX_ACCEPTFILES      = 00010h
WS_EX_TRANSPARENT      = 00020h
WS_EX_MDICHILD	       = 00040h
WS_EX_TOOLWINDOW       = 00080h
WS_EX_WINDOWEDGE       = 00100h
WS_EX_CLIENTEDGE       = 00200h
WS_EX_CONTEXTHELP      = 00400h
WS_EX_RIGHT	       = 01000h
WS_EX_LEFT	       = 00000h
WS_EX_RTLREADING       = 02000h
WS_EX_LTRREADING       = 00000h
WS_EX_LEFTSCROLLBAR    = 04000h
WS_EX_RIGHTSCROLLBAR   = 00000h
WS_EX_CONTROLPARENT    = 10000h
WS_EX_STATICEDGE       = 20000h
WS_EX_APPWINDOW        = 40000h
WS_EX_LAYERED	       = 80000h
WS_EX_OVERLAPPEDWINDOW = WS_EX_WINDOWEDGE or WS_EX_CLIENTEDGE
WS_EX_PALETTEWINDOW    = WS_EX_WINDOWEDGE or WS_EX_TOOLWINDOW or WS_EX_TOPMOST

; System colors

COLOR_SCROLLBAR 	      = 0
COLOR_BACKGROUND	      = 1
COLOR_ACTIVECAPTION	      = 2
COLOR_INACTIVECAPTION	      = 3
COLOR_MENU		      = 4
COLOR_WINDOW		      = 5
COLOR_WINDOWFRAME	      = 6
COLOR_MENUTEXT		      = 7
COLOR_WINDOWTEXT	      = 8
COLOR_CAPTIONTEXT	      = 9
COLOR_ACTIVEBORDER	      = 10
COLOR_INACTIVEBORDER	      = 11
COLOR_APPWORKSPACE	      = 12
COLOR_HIGHLIGHT 	      = 13
COLOR_HIGHLIGHTTEXT	      = 14
COLOR_BTNFACE		      = 15
COLOR_BTNSHADOW 	      = 16
COLOR_GRAYTEXT		      = 17
COLOR_BTNTEXT		      = 18
COLOR_INACTIVECAPTIONTEXT     = 19
COLOR_BTNHIGHLIGHT	      = 20
COLOR_3DDKSHADOW	      = 21
COLOR_3DLIGHT		      = 22
COLOR_INFOTEXT		      = 23
COLOR_INFOBK		      = 24
COLOR_HOTLIGHT		      = 26
COLOR_GRADIENTACTIVECAPTION   = 27
COLOR_GRADIENTINACTIVECAPTION = 28

; Button styles

BS_PUSHBUTTON	   = 0000h
BS_DEFPUSHBUTTON   = 0001h
BS_CHECKBOX	   = 0002h
BS_AUTOCHECKBOX    = 0003h
BS_RADIOBUTTON	   = 0004h
BS_3STATE	   = 0005h
BS_AUTO3STATE	   = 0006h
BS_GROUPBOX	   = 0007h
BS_USERBUTTON	   = 0008h
BS_AUTORADIOBUTTON = 0009h
BS_OWNERDRAW	   = 000Bh
BS_TEXT 	   = 0000h
BS_LEFTTEXT	   = 0020h
BS_RIGHTBUTTON	   = BS_LEFTTEXT
BS_ICON 	   = 0040h
BS_BITMAP	   = 0080h
BS_LEFT 	   = 0100h
BS_RIGHT	   = 0200h
BS_CENTER	   = 0300h
BS_TOP		   = 0400h
BS_BOTTOM	   = 0800h
BS_VCENTER	   = 0C00h
BS_PUSHLIKE	   = 1000h
BS_MULTILINE	   = 2000h
BS_NOTIFY	   = 4000h
BS_FLAT 	   = 8000h

; List box styles

LBS_NOTIFY	      = 0001h
LBS_SORT	      = 0002h
LBS_NOREDRAW	      = 0004h
LBS_MULTIPLESEL       = 0008h
LBS_OWNERDRAWFIXED    = 0010h
LBS_OWNERDRAWVARIABLE = 0020h
LBS_HASSTRINGS	      = 0040h
LBS_USETABSTOPS       = 0080h
LBS_NOINTEGRALHEIGHT  = 0100h
LBS_MULTICOLUMN       = 0200h
LBS_WANTKEYBOARDINPUT = 0400h
LBS_EXTENDEDSEL       = 0800h
LBS_DISABLENOSCROLL   = 1000h
LBS_NODATA	      = 2000h
LBS_NOSEL	      = 4000h
LBS_STANDARD	      = LBS_NOTIFY or LBS_SORT or WS_VSCROLL or WS_BORDER

; Combo box styles

CBS_SIMPLE	      = 0001h
CBS_DROPDOWN	      = 0002h
CBS_DROPDOWNLIST      = 0003h
CBS_OWNERDRAWFIXED    = 0010h
CBS_OWNERDRAWVARIABLE = 0020h
CBS_AUTOHSCROLL       = 0040h
CBS_OEMCONVERT	      = 0080h
CBS_SORT	      = 0100h
CBS_HASSTRINGS	      = 0200h
CBS_NOINTEGRALHEIGHT  = 0400h
CBS_DISABLENOSCROLL   = 0800h
CBS_UPPERCASE	      = 2000h
CBS_LOWERCASE	      = 4000h

; Edit control styles

ES_LEFT        = 0000h
ES_CENTER      = 0001h
ES_RIGHT       = 0002h
ES_MULTILINE   = 0004h
ES_UPPERCASE   = 0008h
ES_LOWERCASE   = 0010h
ES_PASSWORD    = 0020h
ES_AUTOVSCROLL = 0040h
ES_AUTOHSCROLL = 0080h
ES_NOHIDESEL   = 0100h
ES_OEMCONVERT  = 0400h
ES_READONLY    = 0800h
ES_WANTRETURN  = 1000h
ES_NUMBER      = 2000h

; Static window styles

SS_LEFT 	  = 0000h
SS_CENTER	  = 0001h
SS_RIGHT	  = 0002h
SS_ICON 	  = 0003h
SS_BLACKRECT	  = 0004h
SS_GRAYRECT	  = 0005h
SS_WHITERECT	  = 0006h
SS_BLACKFRAME	  = 0007h
SS_GRAYFRAME	  = 0008h
SS_WHITEFRAME	  = 0009h
SS_USERITEM	  = 000Ah
SS_SIMPLE	  = 000Bh
SS_LEFTNOWORDWRAP = 000Ch
SS_BITMAP	  = 000Eh
SS_OWNERDRAW	  = 000Dh
SS_ENHMETAFILE	  = 000Fh
SS_ETCHEDHORZ	  = 0010h
SS_ETCHEDVERT	  = 0011h
SS_ETCHEDFRAME	  = 0012h
SS_TYPEMASK	  = 001Fh
SS_NOPREFIX	  = 0080h
SS_NOTIFY	  = 0100h
SS_CENTERIMAGE	  = 0200h
SS_RIGHTJUST	  = 0400h
SS_REALSIZEIMAGE  = 0800h
SS_SUNKEN	  = 1000h

; Scroll bar styles

SBS_HORZ		    = 0000h
SBS_VERT		    = 0001h
SBS_TOPALIGN		    = 0002h
SBS_LEFTALIGN		    = 0002h
SBS_BOTTOMALIGN 	    = 0004h
SBS_RIGHTALIGN		    = 0004h
SBS_SIZEBOXTOPLEFTALIGN     = 0002h
SBS_SIZEBOXBOTTOMRIGHTALIGN = 0004h
SBS_SIZEBOX		    = 0008h
SBS_SIZEGRIP		    = 0010h

; Dialog styles

DS_ABSALIGN	 = 0001h
DS_SYSMODAL	 = 0002h
DS_3DLOOK	 = 0004h
DS_FIXEDSYS	 = 0008h
DS_NOFAILCREATE  = 0010h
DS_LOCALEDIT	 = 0020h
DS_SETFONT	 = 0040h
DS_MODALFRAME	 = 0080h
DS_NOIDLEMSG	 = 0100h
DS_SETFOREGROUND = 0200h
DS_CONTROL	 = 0400h
DS_CENTER	 = 0800h
DS_CENTERMOUSE	 = 1000h
DS_CONTEXTHELP	 = 2000h

; Menu flags

MF_INSERT	   = 0000h
MF_CHANGE	   = 0080h
MF_APPEND	   = 0100h
MF_DELETE	   = 0200h
MF_REMOVE	   = 1000h
MF_BYCOMMAND	   = 0000h
MF_BYPOSITION	   = 0400h
MF_SEPARATOR	   = 0800h
MF_UNCHECKED	   = 0000h
MF_ENABLED	   = 0000h
MF_GRAYED	   = 0001h
MF_DISABLED	   = 0002h
MF_CHECKED	   = 0008h
MF_USECHECKBITMAPS = 0200h
MF_STRING	   = 0000h
MF_BITMAP	   = 0004h
MF_OWNERDRAW	   = 0100h
MF_POPUP	   = 0010h
MF_MENUBARBREAK    = 0020h
MF_MENUBREAK	   = 0040h
MF_UNHILITE	   = 0000h
MF_HILITE	   = 0080h
MF_DEFAULT	   = 1000h
MF_SYSMENU	   = 2000h
MF_HELP 	   = 4000h
MF_RIGHTJUSTIFY    = 4000h
MF_MOUSESELECT	   = 8000h
MF_END		   = 0080h
MFT_STRING	   = MF_STRING
MFT_BITMAP	   = MF_BITMAP
MFT_MENUBARBREAK   = MF_MENUBARBREAK
MFT_MENUBREAK	   = MF_MENUBREAK
MFT_OWNERDRAW	   = MF_OWNERDRAW
MFT_RADIOCHECK	   = 0200h
MFT_SEPARATOR	   = MF_SEPARATOR
MFT_RIGHTORDER	   = 2000h
MFT_RIGHTJUSTIFY   = MF_RIGHTJUSTIFY
MFS_GRAYED	   = 0003h
MFS_DISABLED	   = MFS_GRAYED
MFS_CHECKED	   = MF_CHECKED
MFS_HILITE	   = MF_HILITE
MFS_ENABLED	   = MF_ENABLED
MFS_UNCHECKED	   = MF_UNCHECKED
MFS_UNHILITE	   = MF_UNHILITE
MFS_DEFAULT	   = MF_DEFAULT
MFR_POPUP	   = 0001h
MFR_END 	   = MF_END

; Border types

BDR_RAISEDOUTER = 01h
BDR_SUNKENOUTER = 02h
BDR_RAISEDINNER = 04h
BDR_SUNKENINNER = 08h
BDR_OUTER	= 03h
BDR_INNER	= 0Ch
BDR_RAISED	= 05h
BDR_SUNKEN	= 0Ah
EDGE_RAISED	= BDR_RAISEDOUTER or BDR_RAISEDINNER
EDGE_SUNKEN	= BDR_SUNKENOUTER or BDR_SUNKENINNER
EDGE_ETCHED	= BDR_SUNKENOUTER or BDR_RAISEDINNER
EDGE_BUMP	= BDR_RAISEDOUTER or BDR_SUNKENINNER

; Border flags

BF_LEFT 		   = 0001h
BF_TOP			   = 0002h
BF_RIGHT		   = 0004h
BF_BOTTOM		   = 0008h
BF_TOPLEFT		   = BF_TOP or BF_LEFT
BF_TOPRIGHT		   = BF_TOP or BF_RIGHT
BF_BOTTOMLEFT		   = BF_BOTTOM or BF_LEFT
BF_BOTTOMRIGHT		   = BF_BOTTOM or BF_RIGHT
BF_RECT 		   = BF_LEFT or BF_TOP or BF_RIGHT or BF_BOTTOM
BF_DIAGONAL		   = 0010h
BF_DIAGONAL_ENDTOPRIGHT    = BF_DIAGONAL or BF_TOP or BF_RIGHT
BF_DIAGONAL_ENDTOPLEFT	   = BF_DIAGONAL or BF_TOP or BF_LEFT
BF_DIAGONAL_ENDBOTTOMLEFT  = BF_DIAGONAL or BF_BOTTOM or BF_LEFT
BF_DIAGONAL_ENDBOTTOMRIGHT = BF_DIAGONAL or BF_BOTTOM or BF_RIGHT
BF_MIDDLE		   = 0800h
BF_SOFT 		   = 1000h
BF_ADJUST		   = 2000h
BF_FLAT 		   = 4000h
BF_MONO 		   = 8000h

include '%finc%/win32/win32a.inc'
include '..\..\..\source\designtime.inc'
include 'winconst.inc'
include '..\..\..\source\AsmEdit\AsmEdit.inc'

DesignTimeInfo                                     \
\ ; AsmEdit control.
        'ASMEDIT',                                    \
        'AsmEdit control',                            \
        'Fresh',                                     \
        'AsmEdit',                                    \
        WS_VISIBLE or WS_CHILD or WS_HSCROLL or WS_VSCROLL or ES_NOHIDESEL or  AES_AUTOINDENT or AES_SMARTTABS or AES_CONSOLECARET, \       ; default style
        WS_EX_CLIENTEDGE,                                          \       ; default ex style
        128, 128,                                  \
        <                                          \       ; style names
            ES_NOHIDESEL,   "Specifies that the selected text is not hidden when the textbox control loses the keyboard focus", \
            AES_AUTOINDENT, 'Auto indent',         \
            AES_SMARTTABS,  'Smart tabs',          \
            AES_OPTIMALFILL, 'Optimal fill',       \
            AES_SECURESEL,   'Security selection', \
            AES_AUTOBRACKETS,'Auto brackets',      \
            AES_CONSOLECARET, 'Console caret',     \
            AES_INDENTSEL,    'Tab indents selection' \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD or ES_MULTILINE,                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $00000000,                                 \            ; This is SubtypeMask
        NONE,                                      \
        NONE,                                      \         ; Library file NULL, because it's standard component.
        'asmedit.ico'

; One file may contains description of more than one control.
; Look at 'DesignTimeInfo' macro definition.
;
; This file must be compiled with FASM compiler to get binary
; file. It will be compiled as .BIN file. This is not executable
; file. Don't start it.

include '..\..\..\source\designtime.inc'
include 'winconst.inc'


DesignTimeInfo                                     \
                                                   \       ; 1. SCROLLBAR CONTROL
        'SCROLLBAR',                               \
        'Horizontal scrollbar control',            \
        'Standard',                                \
        '',                                        \
        WS_VISIBLE+WS_CHILD,                       \       ; default style
        0,                                         \       ; default ex style
        128, 16,                                   \
        <                                          \       ; style names
           SBS_BOTTOMALIGN,  "Aligns scrollbar to the bottom of the client area",   \
           SBS_TOPALIGN,     "Aligns scrollbar to the top of the client area",   \
           SBS_BOTTOMALIGN,  "Aligns scrollbar to the left side of the client area",   \
           SBS_TOPALIGN,     "Aligns scrollbar to the right side of the client area"   \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD,                                  \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $00000001,                                 \            ; This is SubtypeMask
        <                                          \
          SBS_HORZ, 'Horizontal scrollbar',\
          SBS_VERT, 'Vertical scrollbar'\
        >,                                         \            ; This is SubtipeRange
        NONE,                                      \            ; Library file NULL, because it's standard component.
        'hscrollbar.ico',                          \            ; Image for icon
\
\ ; Vertical scrollbar control.
\
        'SCROLLBAR',                               \
        'Sizebox control',                         \
        'Standard',                                \
        ''      ,                                  \
        WS_VISIBLE+WS_CHILD+SBS_SIZEBOX,           \       ; default style
        0,                                         \       ; default ex style
        16, 16,                                    \
        <                                          \       ; style names
           SBS_SIZEBOXBOTTOMRIGHTALIGN,  "Aligns sizebox to the the lower right of the client area",   \
           SBS_SIZEBOXTOPLEFTALIGN,  "Aligns sizebox to the the upper left of the client area"   \
        >,                                         \
        NONE,                                      \            ; style Ex names
\
        $00000000,                                 \            ; This is StyleMaskAnd
        WS_CHILD+SBS_SIZEBOX,                      \            ; This is StyleMaskOr
        $00000000,                                 \            ; This is StyleExMaskAnd
        $00000000,                                 \            ; This is StyleExMaskOr
        $00000001,                                 \            ; This is SubtypeMask
        <                                          \
          SBS_SIZEBOX, 'Standard sizebox',         \
          SBS_SIZEGRIP, 'SizeGrip'                 \
        >,                                         \            ; This is SubtipeRange
        NONE,                                      \            ; Library file NULL, because it's standard component.
        'sizebox.ico'

;--------------------------------------------------------------------
; This is template for creating simple .com DOS application.
;--------------------------------------------------------------------
        org     $100
; Put your source here.





exit:
        mov     ax, $4c00
        int     $21

Simple DOS .com application.

; _______________________________________________________________________________________
;|                                                                                       |
;| ..:: Fresh IDE ::..  template project.                                                |
;|_______________________________________________________________________________________|
;
;  Description: FreshLib portable GUI application; Main form source file;
;
;  Target OS: Any, supported by FreshLib
;
;  Dependencies: FreshLib
;
;  Notes:
;_________________________________________________________________________________________

iglobal
  frmMainForm:
        ObjTemplate  tfEnd, Form, frmMain, \
                     x, 100,        \
                     y, 50,         \
                     width, 320,    \
                     height, 240,   \
                     Visible, TRUE, \
                     Caption, 'FreshLib portable application.'
endg

; _______________________________________________________________________________________
;|                                                                                       |
;| ..:: Fresh IDE ::..  template project.                                                |
;|_______________________________________________________________________________________|
;
;  Description: FreshLib portable GUI application.
;
;  Target OS: Any, supported by FreshLib
;
;  Dependencies: FreshLib
;
;  Notes:
;_________________________________________________________________________________________

include "%lib%/freshlib.inc"

@BinaryType GUI

include "%lib%/freshlib.asm"

; include your includes here.
include "MainForm.asm"

start:
        InitializeAll

        stdcall Create, CApplication
        mov     [pApplication], ebx

        stdcall CreateFromTemplate, frmMainForm, 0
        mov     ecx, [pApplication]
        mov     [ecx+TApplication.MainWindow], frmMain

        stdcall Run

        FinalizeAll
        stdcall Terminate, 0


@AllImportEmbeded       ; or @AllImportSection
@AllDataEmbeded         ; or @AllDataSection

Portable GUI application, based on FreshLib. 
Can be compiled as PE executable or as ELF executable, without source changes.

In order to keep it portable, use only FreshLib functions and avoid use of OS specific API.

; _______________________________________________________________________________________
;|                                                                                       |
;| ..:: Fresh IDE ::..  template project.                                                |
;|_______________________________________________________________________________________|
;
;  Description: FreshLib portable console application.
;
;  Target OS: Any, supported by FreshLib
;
;  Dependencies: FreshLib
;
;  Notes:
;_________________________________________________________________________________________

include "%lib%/freshlib.inc"

@BinaryType console

include "%lib%/freshlib.asm"

; include your includes here.

start:
        InitializeAll

; place your code here.

        FinalizeAll
        stdcall Terminate, 0


@AllImportEmbeded       ; or @AllImportSection
@AllDataEmbeded         ; or @AllDataSection

Portable console application, based on FreshLib. 
Can be compiled as PE executable or as ELF executable, without source changes.

In order to keep it portable, use only FreshLib functions and avoid use of OS specific API.

DLL (dynamic link library).

; DLL library template
format PE GUI 4.0 DLL
entry DllEntryPoint

include '%finc%/win32/win32a.inc'


section '.code' code readable executable

;--------------- DLL entry function --------------------
proc DllEntryPoint, .hinstDLL, .fdwReason, .lpvReserved
begin
        mov     eax,TRUE
        return
endp



;--------------- export functions ----------------------
proc DLLExportFunc, .hWnd, .dwError
begin

        ; insert your code here

        return
endp



section '.idata' import data readable

  ; Place imports here.


section '.edata' export data readable

  ; Place exporting functions here.
  ;
  ; NOTE: functions need to be expoted in
  ; aplhabetical order.

  export 'DLLTPL.DLL',\
         DLLExportFunc,'DLLExportFunc'



section '.reloc' fixups data discardable
  ; Fixup section. You don't have to
  ; put anything here manually.

;<ff
Window frmMain, 2, 0, 'TForm', 'Tiny GUI application using TForm', $16080000, $0, 0, 222, 200, 320, 240, MainFormWinProc;
;ff>

;-----------------------------------------------------------------------
; Window procedure for the form.
; Arguments:
;   .hwnd - handle of the window
;   .wmsg - code of the message
;   .wparam \ Parameters of the message
;   .lparam /
;-----------------------------------------------------------------------
winproc MainFormWinProc
begin
;-----------------------------------------------------------------------
; Write here the code that have to be executed before
; message dispathing.
;-----------------------------------------------------------------------


ondefault
;-----------------------------------------------------------------------
; Write here the code that have to be executed if message
; was not processed by this procedure.
;-----------------------------------------------------------------------
        stc
        return
endwp

Windows GUI applications of type SDI (Single document interface)that
contains only one main window and possibly other dialog or toolbox windows, owned by the main window.

format PE GUI 4.0
entry Start

include '%finc%/win32/win32a.inc'

include "%finc%/libs/msgutils.inc"
include "%finc%/libs/tform.inc"
include "%finc%/libs/parents.inc"
include "%finc%/libs/templates.inc"

include "%finc%/libs/msgutils.asm"
include "%finc%/libs/tform.asm"
include "%finc%/libs/parents.asm"
include "%finc%/libs/templates.asm"

include "MainForm.frm"

uglobal
  hInstance dd ?
  hHeap     dd ?
  hMainForm dd ?
endg

Start:
        invoke  GetModuleHandleA,0
        mov     [hInstance],eax
        invoke  GetProcessHeap
        mov     [hHeap], eax

        InitializeAll

        stdcall CreateForm, frmMain, NULL
        xor     eax, eax
        test    ebx, ebx
        jz      .terminate

        mov     [hMainForm], ebx

.run:
        call    ProcessMessages
        jc      .terminate

        invoke  WaitMessage
        jmp     .run

.terminate:
        push    eax
        FinalizeAll
        invoke  ExitProcess ; exit code from the stack.

data import
  include '%finc%/win32/allimports.asm'
end data

IncludeAllGlobals

Win32 System Tray application template. Includes main window
that creates a tray icon and a popup menu that appears when
user selects the icon.

;<ff
Window frmMainWindow, 2, 0, 'TForm', 'Pluggy', $16080000, $0, 0, 231, 202, 320, 240, MainWindowProc;
;ff>
PM_SHELLNOTIFY = WM_USER + 1

IDI_TRAY     = 0
IDM_EXIT     = 100
IDM_SHOWHIDE = 101


iglobal
  szShowHide db "&Show/Hide", 0
  szExit     db "&Exit", 0
endg

uglobal
  nid          NOTIFYICONDATA
  uVisibleFlag dd ?
  hTrayMenu    dd ?
endg


winproc MainWindowProc
begin

ondefault
        stc
        return

onmessage FM_AFTERCREATE

        mov     [nid.cbSize],sizeof.NOTIFYICONDATA              ; prepare tray icon
        push    [.hwnd]
        pop     [nid.hWnd]
        mov     [nid.uID],IDI_TRAY
        mov     [nid.uFlags],NIF_ICON+NIF_MESSAGE+NIF_TIP
        mov     [nid.uCallbackMessage],PM_SHELLNOTIFY
        invoke  LoadIconA, NULL,IDI_WINLOGO
        mov     [nid.hIcon],eax
        mov     dword[nid.szTip],"Tray"
        mov     dword[nid.szTip+4], "Demo"
        invoke  Shell_NotifyIconA, NIM_ADD,nid

        invoke  CreatePopupMenu                 ; create tray popup menu - here you
        mov     [hTrayMenu],eax                 ; can add your own menu items
        invoke  AppendMenuA, eax,MF_STRING,IDM_SHOWHIDE,szShowHide
        invoke  AppendMenuA, [hTrayMenu],MF_STRING,IDM_EXIT,szExit
        clc
        return

onmessage WM_DESTROY
        invoke  Shell_NotifyIconA, NIM_DELETE,nid
        invoke  DestroyMenu, [hTrayMenu]
        invoke  PostQuitMessage, 0
        clc
        return

onmessage WM_COMMAND
        cmp     [.lparam],0
        jne     .ondefault

        mov     eax,[.wparam]           ; handle tray popup menu actions
        cmp     eax,IDM_SHOWHIDE        ;
        je      .showhide
        cmp     eax,IDM_EXIT
        je      .idm_exit
        stc
        return

  .idm_exit:
        invoke  DestroyWindow, [.hwnd]
        clc
        return


onmessage WM_CLOSE
        jmp     .hide

onmessage PM_SHELLNOTIFY                ; handle tray icons actions:
locals                                  ;  left mouse button - show/hide window
  .pt POINT                             ;  right mouse button - show tray popup menu
endl
        cmp     [.lparam],WM_LBUTTONDOWN
        je      .showhide
        cmp     [.lparam],WM_RBUTTONDOWN
        je      .show_tray_popup
        jmp     .finish
  .showhide:
        cmp     [uVisibleFlag],0
        je      .show
      .hide:
        invoke  ShowWindow, [.hwnd],SW_HIDE
        mov     [uVisibleFlag], 0
        jmp     .finish
      .show:
        invoke  ShowWindow, [.hwnd],SW_SHOW
        mov     [uVisibleFlag], 1
        invoke  SetActiveWindow, [.hwnd]
        jmp     .finish
  .show_tray_popup:
        lea     eax,[.pt]
        invoke  GetCursorPos, eax
        invoke  SetForegroundWindow, [.hwnd]
        invoke  TrackPopupMenu, [hTrayMenu],TPM_RIGHTALIGN,[.pt.x],[.pt.y],\
                                NULL,[.hwnd],NULL
        invoke  PostMessageA, [.hwnd],WM_NULL,0,0
  .finish:
        clc
        return
endwp

format PE GUI 4.0
entry Start

include '%finc%/win32/win32a.inc'
include '%finc%/libs/msgutils.inc'
include '%finc%/libs/templates.inc'
include '%finc%/libs/TForm.inc'
include '%finc%/libs/parents.inc'


section '.code' code readable executable
..ShowSizes = 1
..ShowSkipped = 0

include '%finc%/libs/msgutils.asm'
include '%finc%/libs/templates.asm'
include '%finc%/libs/TForm.asm'
include '%finc%/libs/parents.asm'

include 'mainwindow.frm'

uglobal
  hMainForm dd ?
  hInstance dd ?
endg

Start:
        invoke  GetModuleHandleA, 0
        mov     [hInstance], eax
        InitializeAll

        stdcall CreateForm, frmMainWindow, NULL
        mov     [hMainForm],ebx

        include '%finc%/libs/mainloop.asm'
        push    eax
        FinalizeAll
        invoke  ExitProcess


section '.idata' data import readable writeable
ImportTable:
include '%finc%/win32/allimports.asm'
DispSize 'ImportTable', $ - ImportTable

section '.data' data readable writeable
IncludeAllGlobals

; Console Modes, and color atributes

ENABLE_PROCESSED_INPUT          = 1h
ENABLE_LINE_INPUT               = 2h
ENABLE_ECHO_INPUT               = 4h
ENABLE_WINDOW_INPUT             = 8h
ENABLE_MOUSE_INPUT              = 10h
ENABLE_PROCESSED_OUTPUT         = 1h
ENABLE_WRAP_AT_EOL_OUTPUT       = 2h
CONSOLE_TEXTMODE_BUFFER         = 1
FOREGROUND_BLUE                 = 1h
FOREGROUND_GREEN                = 2h
FOREGROUND_RED                  = 4h
FOREGROUND_INTENSITY            = 8h
BACKGROUND_BLUE                 = 10h
BACKGROUND_GREEN                = 20h
BACKGROUND_RED                  = 40h
BACKGROUND_INTENSITY            = 80h

struct COORD
  .x                            dw ?
  .y                            dw ?
ends

struct SMALL_RECT
  .Left                         dw ?
  .Top                          dw ?
  .Right                        dw ?
  .Bottom                       dw ?
ends

struct CONSOLE_SCREEN_BUFFER_INFO
  .dwSize                       COORD
  .dwCursorPosition             COORD
  .wAttributes                  dw ?
  .srWindow                     SMALL_RECT
  .dwMaximumWindowSize          COORD
ends

; Console Colors

macro ConsoleColor Name,[Part] {
 common
   local Color
   Color = 0
 forward
   if ~ Part eq
     Color = Color or FOREGROUND_#Part
   end if
 common
   FGColor.#Name = Color
   BGColor.#Name = (Color shl 4)
}

ConsoleColor Black
ConsoleColor Gray,INTENSITY
ConsoleColor Silver,RED,GREEN,BLUE
ConsoleColor White,RED,GREEN,BLUE,INTENSITY
ConsoleColor Maroon,RED
ConsoleColor Red,RED,INTENSITY
ConsoleColor Navy,BLUE
ConsoleColor Blue,BLUE,INTENSITY
ConsoleColor Green,GREEN
ConsoleColor Lime,GREEN,INTENSITY
ConsoleColor Purple,RED,BLUE
ConsoleColor Pink,RED,BLUE,INTENSITY
ConsoleColor Olive,RED,GREEN
ConsoleColor Yellow,RED,GREEN,INTENSITY
ConsoleColor Teal,BLUE,GREEN
ConsoleColor Cyan,BLUE,GREEN,INTENSITY

; Console Procedures

iglobal
  CSBI          CONSOLE_SCREEN_BUFFER_INFO
  coords        COORD
endg

uglobal
  hStdIn        dd ?
  hStdOut       dd ?
  ConsoleBuffer rb 1024
endg

; FUNCTION SetColor (Color)
; Changes the Console color.
Console.SetColor fix [SetConsoleTextAttribute],[hStdOut]

initialize PrepareConsole
begin
    xor         eax,eax
    mov         dword [coords],eax

    invoke      GetStdHandle,STD_INPUT_HANDLE
    cmp         eax,INVALID_HANDLE_VALUE ;If theres an error, dont open the console
    je          .end
    mov         [hStdIn],eax ;else, save the input handle
    invoke      GetStdHandle,STD_OUTPUT_HANDLE
    cmp         eax,INVALID_HANDLE_VALUE ;If theres an error, dont open the console
    je          .end
    mov         [hStdOut],eax ;else save the output handle
    invoke      SetConsoleMode,[hStdIn],ENABLE_PROCESSED_INPUT or ENABLE_LINE_INPUT or ENABLE_ECHO_INPUT or \
                                                ENABLE_MOUSE_INPUT or ENABLE_WINDOW_INPUT or ENABLE_PROCESSED_OUTPUT or \
                                                ENABLE_WRAP_AT_EOL_OUTPUT
    stdcall     Console.SetColor,FGColor.Silver or BGColor.Black
  .end:
    return
endp

; FUNCTION Print (Text)
; Print a text to the console.
proc Console.Print,.strText
  .WB dd ?
begin
     push       edx
     invoke     lstrlen,[.strText]
     lea        edx,[.WB]
     invoke     WriteConsoleA, [hStdOut], [.strText], eax, edx, 0
     pop        edx
.end:
     return
endp


; FUNCTION Input
; Read one text from the console.
; Returns pointer to buffer.
proc Console.Input
  .RB dd ?
begin
     invoke     FlushConsoleInputBuffer,[hStdIn]
     lea        eax,[.RB]
     invoke     ReadConsoleA,[hStdIn],ConsoleBuffer,1024,eax,0
     mov        esi,ConsoleBuffer ; starting the routine to remove the crlf chars
.loadstrloop:
     lodsb
     cmp        al,13
     jne        .loadstrloop
     mov        byte [esi-1],0
     mov        eax,ConsoleBuffer
     return
endp

; FUNCTION Locate (X,Y)
; Changes the cursor position.
proc Console.Locate,.curX,.curY
begin
     mov        eax,[.curX]
     mov        dword [coords.x],eax
     mov        eax,[.curY]
     mov        dword [coords.y],eax
     invoke     SetConsoleCursorPosition,[hStdOut],[coords]
     return
endp

; FUNCTION Clear (Color)
; Clears the console.
proc Console.Clear,.paramColor
  .WB dd ?
begin
     mov        [coords.x],0
     mov        [coords.y],0
     stdcall    Console.SetColor,[.paramColor]
.next:
     invoke     GetConsoleScreenBufferInfo,[hStdOut],CSBI
     mov        eax,dword [CSBI.dwSize.x]
     mul        [CSBI.dwSize.y]
     ; conSize = edx
     lea        eax,[.WB]
     invoke     FillConsoleOutputCharacterA,[hStdOut],20h,edx,[coords],eax
     invoke     GetConsoleScreenBufferInfo,[hStdOut],CSBI
     lea        eax,[.WB]
     invoke     FillConsoleOutputAttribute,[hStdOut],dword [CSBI.wAttributes],edx,[coords],eax
     invoke     SetConsoleCursorPosition,[hStdOut],[coords]
     return
endp

; FUNCTION SetTitle (Title)
; Changes the console title.
Console.SetTitle equ [SetConsoleTitleA]

; Win32 Console Application

format PE Console 4.0
entry Start

include '%finc%\win32\win32a.inc'
include 'Console.inc'

uglobal
  hInstance dd ?
  hHeap     dd ?
endg

Start:
        invoke  GetModuleHandleA,0
        mov     [hInstance],eax
        invoke  GetProcessHeap
        mov     [hHeap], eax
        InitializeAll

        ; TODO: Insert code here

        ; Start of example
        iglobal
          strTest       db ' Hello world! ',0
          strEnding     db 'Ending application, press any key...',13,10,0
          strTitle      db 'Testing Console Library',0
        endg
        stdcall Console.Locate,5,5
        stdcall Console.SetColor,FGColor.Maroon or BGColor.Pink
        stdcall Console.SetTitle, strTitle
        stdcall Console.Print, strTest
        stdcall Console.Input
        stdcall Console.Clear, FGColor.Red or BGColor.White
        stdcall Console.Print, strEnding
        stdcall Console.Input
        ; End of example

Exit:
        push    eax
        FinalizeAll
        invoke  ExitProcess ; exit code from the stack.

data import
  include "%finc%\win32\allimports.asm"
end data

IncludeAllGlobals

Windows 32-bit console type applications.

;<ff
Window FormLabel, 2, 0, 'TForm', 'TForm window', $16080000, $0, 0, 201, 191, 320, 240, CustomWinProc;
;ff>

;-----------------------------------------------------------------------
; Window procedure for the form.
; Arguments:
;   .hwnd - handle of the window
;   .wmsg - code of the message
;   .wparam \ Parameters of the message
;   .lparam /
;-----------------------------------------------------------------------
winproc CustomWinProc
begin
;-----------------------------------------------------------------------
; Write here the code that have to be executed before
; message dispathing.
;-----------------------------------------------------------------------


ondefault
;-----------------------------------------------------------------------
; Write here the code that have to be executed if message
; was not processed by this procedure.
;-----------------------------------------------------------------------
        stc
        return
endwp

The Fresh Artistic License

Preamble

The intent  of  this document is to  state the conditions under which a
Package may be  copied,  such that the  Copyright Holder maintains some
semblance of  artistic control  over the  development  of  the package,
while giving  the users  of the package the right to use and distribute
the Package in a more-or-less customary fashion, plus the right to make
reasonable modifications.

Definitions:

    * "Package" refers  to  the  collection of files distributed by the
      Copyright Holder,  and derivatives  of that  collection  of files
      created through textual modification.
    * "Standard Version"  refers  to  such a Package if it has not been
      modified,  or has  been modified in accordance with the wishes of
      the Copyright Holder.
    * "Copyright Holder"  is  whoever  is  named  in  the  copyright or
      copyrights for the package.
    * "You"  is  you,  if you're thinking about copying or distributing
      this Package.
    * "Reasonable copying fee" is whatever you can justify on the basis
      of media cost,  duplication charges, time of people involved, and
      so on. (You  will  not be required to justify it to the Copyright
      Holder, but  only to the computing community at large as a market
      that must bear the fee.)
    * "Freely Available"  means  that  no  fee  is charged for the item
      itself,  though  there may be fees involved in handling the item.
      It  also  means  that recipients of the  item may redistribute it
      under the same conditions they received it.

IMPORTANT NOTE: 
    FASM compiler itself,  which  is  integral  part of this package is 
    distributed under  different  license.  All  source  files  of FASM 
    compiler are separated in "source\fasm\" directory. Please read and 
    apply "source\fasm\license.txt" for FASM license.

1. You may make and give away verbatim copies of the source form of the
   Standard Version  of this Package without restriction, provided that
   you duplicate all  of the  original copyright notices and associated
   disclaimers.

2. You may apply bug fixes, portability fixes  and other  modifications 
   from the Copyright Holder  or those  derived  from the Public Domain 
   and approved by the  Copyright Holder.  A Package modified in such a 
   way shall still be considered the Standard Version.

3. You  may  otherwise  modify  your  copy  of this Package in any way,
   provided  that you  insert  a prominent notice  in each changed file
   stating how and when you changed that file, and provided that you do
   at least ONE of the following:

    a) place your modifications in the Public Domain or  otherwise make
       them Freely Available, such as by posting said  modifications to
       Usenet or an equivalent medium, or placing the  modifications on
       a major  archive site  such as  ftp.uu.net,  or by  allowing the
       Copyright Holder  to include  your modifications in the Standard
       Version of the Package.

    b) use   the  modified  Package  only  within  your  corporation or
       organization.

    c) rename any non-standard executables so the names do not conflict
       with  standard  executables,  which  must  also be provided, and
       provide a separate manual page for each  non-standard executable
       that clearly documents how it differs from the Standard Version.

    d) make other distribution arrangements with the Copyright Holder.

4. You may  distribute  the programs  of this Package in object code or
   executable form, provided that you do at least ONE of the following:

    a) distribute  a  Standard  Version  of the executables and library
       files,  together  with  instructions  ( in  the  manual  page or
       equivalent) on where to get the Standard Version.

    b) accompany  the  distribution with the machine-readable source of
       the Package with your modifications.

    c) accompany any non-standard executables with their  corresponding
       Standard    Version   executables,   giving   the   non-standard
       executables  non-standard  names,  and  clearly  documenting the
       differences  in  manual  pages  (or equivalent),  together  with
       instructions on where to get the Standard Version.

    d) make other distribution arrangements with the Copyright Holder.

5. You may charge a reasonable copying fee for any distribution of this
   Package.  You  may  charge  any  fee  you choose for support of this
   Package. You may not charge a fee for this  Package itself. However,
   you may  distribute  this  Package in aggregate with other (possibly
   commercial)  programs  as  part  of  a  larger (possibly commercial)
   software  distribution  provided  that  you  do  not  advertise this
   Package as a product of your own.

6. The executable and library files supplied as input to or produced as
   output from the  programs  of this Package do not automatically fall
   under  the  copyright  of  this  Package,  but  belong  to  whomever
   generated  them, and may be sold commercially, and may be aggregated
   with this Package.

7. You may not use this package,  nor files created as output from this
   package,  nor  products  derived  from  this  package for producing,
   distrubuting  or  in  any   way   contribute   to  the  creation  or
   distribution of "unwanted advertisement" (known as SPAM).

8. The name  of  the  Copyright  Holder  may  not be used to endorse or
   promote  products  derived from this software without specific prior
   written permission.

9. THIS PACKAGE IS PROVIDED "AS IS"  AND WITHOUT ANY EXPRESS OR IMPLIED
   WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
   MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

The End

"Fresh" project
(c)2003...2011, 2012 Fresh developement team

This file is in the root directory of the Fresh RAD IDE.
Fresh is FASM based self compilable RAD IDE.

To browse and compile Fresh sources, use recent version of the
FASMW compiler or Fresh IDE itself.

For more detailed information how to write applications with Fresh,
read "doc/FreshGuide.chm" file.

For the sources look at: "source\" directory.

Also the repository with the project history and latest dev versions is on:
[http://chiselapp.com/user/johnfound/repository/FreshIDE/index]

To get latest version of Fresh, visit Fresh home page: http://fresh.flatassembler.net

For FASM/FASMW information and downloads: http://flatassembler.net

To contact authors of Fresh and/or FASM: http://board.flatassembler.net

This file describes the changes in every new version of Fresh IDE
The date format: DD.MM.YYYY

version 2.0.10 (??????????)

    [-] Fixed bug concerning working in Linux (Wine). When Fresh compiles some ELF executable
        it could not set the executable permissions. Now it is fixed.

    [+] New feature: When no Linux terminal is configured, Fresh runs the Linux ELF binaries
        directly, without terminal.

version 2.0.9 (22.09.2012)

    [!] This release introduces some incompatibility with the earlier sources. Read below.

    [+] New FASM 1.71 compiler with address space labels.

    [+] Removed GlobalAPI symbol. Now, when Win32 API is used, the user must provide the
        full function name. This approach makes the syntax more simple, clear and portable.

    [+] Merged with FreshLibDev - new "uses" macro, more flexible dll import macros.
        New "text" macro that avoids text constants duplication. Stdcall macros now
        allows using string constants directly.

    [+] Examples and project templates adapted to the new style of importing functions.

    [-] Fixed missing syntax highlighting of the data definition directives.

    [-] Fixed rare bug - crash when some file is 1.in the project, 2.does not exists on disk
        and 3.the user choose to keep it in the project. Then on compilation, when the compiled
        file uses this missing file, Fresh crashes.

    [-] Fixed long waiting bug with editor "indent" and "comment" features, that made one more line
        to be commented/indented.

version 2.0.8 (26.08.2012)

    [+] Merged with the latest FreshLibDev with sockets library.
    [-] Fixed buggy behaviour of the background .fas file processing.
    [-] Fixed wrong working directory of andLinux running applications.


version 2.0.7 (22.07.2012)

    [+] Added new application templates - FreshLib based portable console and
        GUI applications.
    [-] Empty templates removed.
    [-] "New application" template dialog behavior fixed.
    [+] Latest version of FreshLibDev merged.
    [+] FASM 1.70.03 compiler.
    [+] New help file with FASM 1.70 manual and FreshLib reference.
    [+] New feature: "Help file Ctrl+F1" - the user can open the configured
        help files individually.
    [+] New feature: Embeded help. Fresh extracts the comment blocks from the
        source files and displays them as a hint in the editor.
    [+] Time consuming processing of the .fas file was moved to the
        background thread and does not slow the IDE.
    [+] The cross-reference window can be closed by ESCAPE key from the editor.
    [+] Autoinstalation now set FreshGuide.chm as a help file.
    [-] More FreshLib and less Win API used.
    [-] Increased default memory, allocated for the compiler.
    [-] Some obscure bugs fixed, including all tickets from the repository.

version 2.0.6 alpha (27.04.2012)

    [+] More informative error messages when missing debug information.
    [+] Symbols cross reference functions (in the label explorer and in the source editor)
    [+] Latest version of FreshLib
    [+] Updated FASM compiler to version 1.70
    [-] Some bugs fixed

version 2.0.5 alpha (13.01.2012)

    [+] Native support for running and debuging Linux executables. Now Fresh can run in
        Linux|Wine and to run ELF executables directly.
    [-] Fixed bug in the editor themes load/save dialog. There is still some inconsistent
        behavior, that have to be fixed later.

version 2.0.4 alpha (25.12.2011)

    [+] Updated FASM compiler to 1.69.35
    [+] The project is managed by Fossil VCS now.
        The repository is hosted on [http://chiselapp.com/user/johnfound/repository/FreshIDE]
        Of course the full source code is still available with the release packages,
        but it is often outdated, especially in FreshLib part that is in heavy development now.
    [+] Merged with the latest development version of FreshLib.
    [-] Fixed old bug. Now in form editor ESC key works - selects the parent window in properties editor.
    [-] Fixed bug in form editor that was unable to create new forms.

version 2.0.3 alpha (15.01.2011)

    [+] The next in a row, big restructure of the source code:

        FreshLib is implemented for following libraries:
           - macros (macro/allmacros.asm)
           - equates (equates/allequates.asm)
           - imports (imports/allimports.asm)
           - the structure of the program ( compiler/executable.inc )
           - memory allocations ( data/memory.asm )
           - data handling (data/arrays.asm; data/memstream.asm)
           - file operations (data/files.asm)
           - String operations (data/strlib.asm) StrLib is now portable as well.
             For details, read the header of StrLib.asm file.
             Some functions are not backward compatible with the old version.

    [+] Updated compiler to FASM v1.69.29
    [+] New 'text' macro introduced. The final goal is to provide automatic handling
        of the string constants in order to avoid duplications in definitions and
        waste of label names. Unfortunately, the speed of the macros is too low for
        practical use, so now only a stub is provided for future development.
    [-] Auto set for "lib" directory alias in Fresh.ini
    [-] Fixed bug in AsmEdit
    [-] Fixed bug in AddCompilationStatistics (fasm.asm)
    [-] Fixed very old bug in LabelsList.asm.

version 2.0.2 alpha (23.11.2010) - silent release :)

    [-] Fixed bug in editorhost.asm that crashed Fresh in some cases.
    [-] Fixed bug in PAHint.asm
    [-] Fixed some include files, not properly updated after changes for this version.
    [-] Fixed example projects that refused to compile, because of the updates.
        It was because of biger memory needed and because of some not fixed include files.
    [-] some Cleanup in the XLib example to make it smaller and cleaner.
    [-] Fixed macro/exceptions.inc library to use the new FASM macro syntax.

version 2.0.2 alpha (22.11.2010)
    API include files replaced with new, builded with ImportDB tool. Several bugs fixed.

    [+] Replaced all import files. There is no apia and apiw directories but only one "api".
        All API files are build with ImportDB utility and contains almost all API functions
        from WinXP dlls. Also, the api files now contain the argument description for almost
        all API functions.
        The type of api is set with GlobalAPI symbolic constant. It accepts following values:

            GlobalAPI equ               ; empty value means, all functions will be imported
                                        ; exactly as they are exported from the libraries.

            GlobalAPI equ ascii         ; ASCII functions will be imported without suffix.
                                        ; Unicode functions will be imported with suffix W.

            GlobalAPI equ unicode       ; ASCII functions will be imported with suffix A
                                        ; Unicode functions will be imported without suffix.

    [-] Changed font of the procedure arguments hint window to "Trebuchet MS" that is
        more readable for programming needs.
    [-] buttonedit.asm and buttonedit.inc moved to '%finc%\libs\' where is the
        right place for these files.
    [-] Minor changes in some of component libraries (TForm and Action lists.)
        in order to cleanup dependencies with other libraries.
    [-] Fixed bug on counting arguments in PAHint, when there are quoted commas
        in the arguments.
    [-] Fixed bug on fake compilation that caused crash in some circumstances.
    [-] Fixed very old bug in ButtonEdit.asm, that manifested itself only in Wine.
    [-] Fixed bug in TDataGrid, that sometimes caused crash on closing Fresh.

version 2.0.1 alpha (14.11.2010)

    One new feature and several bug fixes.

    [+] Procedure arguments hint - when the user type call statements, it shows arguments
        of the procedure. It can be used with imported functions too, but the argument
        descriptions for these is limited for now.
    [-] Changes in CCList.asm in order to make things more clear and to collect the code
        in one place.
    [-] Partially edited user32.inc file to insert procedure arguments.
    [-] Fixed wrong size on save of editor theme.
    [-] Bug fix in TForm window class. It concerns the proper WM_COMMAND processing when
        the form is open as modal dialog and have some parent.
    [-] Fixed missing file from the template directory.
    [-] Several other bug fixes here and there.


version 2.0.0 alpha (09.11.2010)

    First version officially published after the project revival. :)

    [+] New project format with converter from the old projects.
    [+] New Linux execution engine, based on andLinux.
    [+] New icon set.
    [+] New help system, that allows multiply help files to be searched.
    [+] New interface to FASM compiler.
    [-] Many bugfixes here and there.
    [-] Little bug fixed in "Create new application" function.

Setup manual
# Chapter 4 Fresh IDE setup

    The upcoming version 3.0 of Fresh IDE will be fully portable, but until then,
we have to use the Windows version of Fresh.

    Nevertheless, development of Windows and Linux applications in the same time is possible 
    and easy with the current version of Fresh.

    The good news are that Fresh IDE runs like a charm in [Wine].

    So, now (since v2.0.5) we have a choice - whatever OS we choose we can develop applications
for Linux and Windows, including editing, compiling, running and debugging. Of course we are
talking about GUI applications.

    The installation of Fresh is easy, but if we want to use the full potential of the IDE
some setup and adjustments are necessary. Let see how to setup Fresh IDE for work in Windows 
and Linux:

[wine] http://www.winehq.org/


## Windows setup

    In order to run Linux native applications inside Windows, Fresh uses special Linux
distribution - [andlinux].

    *andLinux* is complete Ubuntu distribution, that uses coLinux kernel in order to allow
running of Linux inside Windows OS.

[andLinux] http://andlinux.org
[andLinux download page] http://andlinux.org/downloads.php

    How to setup andLinux to work with Fresh?

### Download andLinux

    Download andLinux package from [andLinux download page]

    There are two packages: "KDE version" and "minimal/XFCE version" available. For use with
Fresh IDE, it is not important what version you will choose.

    KDE package is very big and very slow distribution that contains many bundled programs
and tools, but in general you will not need them. The size of KDE package is 500MB download
and 5GB installed.

    The XFCE package is relatively smaller and faster. Relatively means 200MB downloaded file
and 2GB installed on the disk.

    It is obvious that the right choice is to use XFCE package.

### Install andLinux

    Run the downloaded setup file and answer to the different questions of the
setup wizard:

    * coLinux version - choose the stable version (0.7.4 in my case) instead of latest (0.8.0) - 
we shall work with andLinux, not to play.

    * Memory size - 256MB RAM (or maybe more - if you can afford it).

    * Install XMing server on your primary screen.

    * Sound - you can enable or disable sound in Linux option - it is harmless although
it is one more running server.

    * Startup type + Panel - select *"run andLinux automatically as a NT service" + "use Windows shortcuts"*;
It is not very important, but can save you a little manual work and troubles later.

    * andLinux login - just select your user name and password for Linux root.

    * Windows File Access - it is important! - select *"using CoFS"*, no matter it is not recommended.

    * File Access Using CoFS - important! - create one new directory somewhere and select it to
be mount via CoFS. This will be the shared directory, visible from Windows and from Linux in the
same time.

    All other features you can choose freely or simply leave them to default state.

    When you start installation, the installer will try to install network driver.
It is possible Windows will protest and will atempt to mislead you by asking to not install
not certified driver. You must ignore these attempts and firmly click "install".

    After the installation of andLinux, you have to restart Windows and probably andLinux will
not run. :)

    It is because of the Windows firewall. All new network adapters are firewalled
by default. As long as installed adapter (named TAP-Colinux) is virtual and local, you will
not need any firewall, so, go to "Control panel/Windows firewall/Advanced" and uncheck
"TAP-Colinux" adapter from the list of adapters.

    Then you can run some Linux program - in the Windows tray, there is a andLinux menu icon
that have shortcuts to several Linux programs.


### Additional tools

    Install several additional Linux tools. You will need additionally debugger and
some decent terminal emulator. I choose xterm for terminal, because it is small and white by
default. ;)

    You can choose to use the built-in terminal named in the simple Linux manner:
"xfce4-terminal" and console debugger "gdb". In this case you can skip this step because these tools
are already installed.

    Start "Synaptic" - package manager for Ubuntu from the tray menu. You have to enter root
password you choose on install.

    When Synaptic is started, click "Reload" to refresh the package list from the network and
then use search to locate needed programs. I personally recommend "xterm" as terminal and "ddd"
as a GUI front end to "gdb".

    Well, I recommend "ddd" only because it is only Linux debugger that I was able to run under
andLinux and able to show disassembled code of the program.

    Mark selected programs for install, click on Apply button and wait until downloading and
installation.

    Here you can encounter only one problem - your computer is behind a proxy server.

    If the proxy is a normal proxy, you simply have to set its address and port in the
Synaptic preferences and it should work.

    Completely another story is when the proxy is MS ISA server configured with NTLM user
authorization.

    Most Linux programs can't work with such authorization and Synaptic is not an exception.

    Fortunately, there is a workaround of this situation. You need [ntlmaps] authorization 
proxy server.

    Setting up of this server is out of the scope of this article. On the ntlmaps home page you
can read complete documentation and explanations.

    OK, we are ready with andLinux. Now you have working copy of Ubuntu inside your Windows box.

    It's time to configure Fresh to run Linux applications inside andLinux. Continue with:

[ntlmaps] http://ntlmaps.sourceforge.net/

### Fresh IDE configuration.

    Run Fresh and open "Options|IDE options" dialog. Select "Debuggers and Emulators" page.
    Then select following directories and commands:

    * "andLinux directory" - the directory where you installed andLinux.

    * "andLinux shared directory" - shared directory you selected during andLinux installation.

    * "Linux debugger" - Enter "ddd" (or whatever debugger you choose).

    * "Linux terminal" - Enter: `xterm -hold +mesg -e` - the options are important.

    *And voila! You finished the configuration!*

    Now you can load the source of some Linux program (for example "Fresh/examples/XLib/XLib.fpr") and run it with
shift+F9 or load it in the debugger with shift+F8.

    Now Fresh IDE will detect when you compiled ELF executable and will run it in andLinux instead of
Windows. Of course, the Windows applications will be treated as usually.


## Linux setup

    Working in Linux needs Wine installation. Fresh is tested with v1.2 and 1.3 and works great.
You can skip some steps if they are already set.

### Install Wine

    Install Wine - use whatever package manager is good for you. Synaptic is the usual choice.
In the "Wine configuration|Graphics" panel, uncheck the option "Allow the window manager to decorate the windows".

### Install Fresh IDE

    Install Fresh IDE v2.0.5 or newer - you can use the installation package or ZIP
archive. It is better (at least for v2.0.5) to install Fresh IDE in "c:\" but you can put it at
whatever place you like.

### Debuggers

    Install whatever debugger you will use for Linux applications and OllyDbg for
Windows applications. (OllyDbg works in Wine).

    For Linux, personally I prefer [EDB] but any other is OK
including mentioned in the previous chapter "ddd" and "gdb".

[edb] http://www.codef00.com/projects#Debugger

### Configure Fresh IDE

Run Fresh IDE and if some paths are not set properly, set them manually in
"Options|IDE options" menu.

    You will need at least following directory aliases: "Fresh", "finc" and "lib" - set
them respectively to the Fresh main directory, Fresh "include" directory and "freshlib"
directory, both located in Fresh main directory. (As a rule, there is an auto setup of these
paths, so you don't to have to make it manually. But sometimes the algorithm fails)

    In order to work with FASM examples and programs, you can set manually "include" or any
other alias (environment variable) you prefer.

### External tools

    Set the paths to the external tools needed: (of course you have to install these
tools in advance).

    In "Options|IDE options|Debuggers and emulators" leave "andLinux directory" and
"andLinux shared directory" fields empty. (they are not needed when Fresh runs in Linux)

    Set "Linux debugger" field to binary file of the debugger you prefer. Add the needed
options to the line as well.

    For example, in my settings "Linux debugger" is set to `z:/usr/bin/edb --run`

    Set "Linux terminal" to preferred terminal. For example `z:/usr/bin/xterm -hold +mesg`.

    Set "Win32 external debugger" to OllyDbg.
In my case: `c:\Program files\OllyDebugger\Ollydbg.exe`.

    *All paths must be "dos style" (Note: Wine maps Linux file system to device Z: ).*

### Test it

    Try to compile and run some test applications both for Windows and Linux.
Ctrl+F9 should compile, Shift+F9 should run the application and Shift+F8 should load it
in the respective debugger. The type of the application should be automatically determined.

    *IMPORTANT NOTE:* The only known problem (for Fresh v2.0.5) is that the first time compiled
ELF is not set to be executable. So, you will get "access denied" message on run. The workaround
is to set the permissions manually from the file manager, or console "chmod" command. It is one
time procedure - the following compilations, runs and debugs should work properly.

Tips and tricks
# Chapter 5 Fresh tips and tricks.

    There is still no full user guide for Fresh.

    I will write in this page some tips and tricks. Later, they will be used in the full user guide.


## Linux support

* How to develop Linux application from Windows?

* How to develop Windows application from Linux?

* What about Fresh IDE version for Linux?

    For now, Fresh is Windows application. The versions 2.x.x will be Windows applications.
The upcoming v3.0.0 is planed to be portable - for Windows and Linux. Of course every port
will be able to create applications for every OS.

    Despite of this situation, even the current versions can work in Linux through Wine.

    There is a separate [setup][setup manual] describing the setup of Fresh IDE for Linux development.

[setup] 0_advanced_setup.htm

## Goto address

    How to find the place in the source where application crashes?

    Press Ctrl+G in order to open "Goto address" dialog:

        [!goto][Goto address]

    Then enter the address where application crashes and press OK. Fresh will show you the
line of the source that is compiled on the given address. The format of the number is standard
FASM number format.


## Code exploration and cross reference.

There are several functions, aimed to provide easy exploration the source of the big project.

### Labels explorer

After compilation, you can browse all labels tree from the labels explorer. Open it from the 
main menu: `Project|Label explorer`.
In the label explorer you can view the lables values, type and where in the source these labels 
was defined and used.

### Editor cross reference

If you position the text caret on some label and press Ctrl+R, or choose from context menu 
"Cross reference", a window with the cross reference information for this label will be open.

          [!cross][Cross reference]

The first row of the table display the line of the source, label was defined. 
Following rows - the lines where the label is used. Besides the pointed label, all its 
children labels will be displayed.s

If you double click on some of the rows, the editor will bring you to this line of source.

The cross reference window can be closed by pressing *Esc* key.

## Goto definition

If you position the text caret on some symbol and press *Ctrl+D* or choose from the context menu 
"Goto definition", the editor will bring you to the line of the source where this symbol were 
defined.
The project must be compiled for this function to work.

## Embeded help

Similar to "Goto definition" is the next function "Embeded help". 

If the definition of some symbol is preceded by comments block, describing this symbol, Fresh can
show this description everywhere in the source, when you position the text caret on the symbol and
press *Ctrl+W* shortcut. 

The hint window looks like on the screenshot:

                    [!_images/EmbededHelp.png][Embeded help system]

The hint window can be closed by pressing *Esc* key.

## Arguments hint

    How to use "Procedure arguments hint"?

        [!procarg][Procedure argument hints]

    This function works with call macros: *stdcall, ccall, invoke and cinvoke*;

    When you type such line and the function is known (the source have to be compiled prior to
that moment) Fresh shows a hint window that helps you to enter the arguments. This happens
automatically when you type "," somewhere in the line.

    When you want to open the hint window without typing (just for check up) you can press
Ctrl+Q when the caret is at the line. You can close the hint window, pressing *Esc* key.

    "Procedure argumens hint" works for the procedures defined in the compiled source and if
the program uses import definitions from FreshLib, for imported functions as well.

## Code completion

    How to type less and to code more?

        [!code][Code completion]

    Code completion is very powerful function, that can save you thousands of keystrokes.
In order to use it, the source have to be compiled (at least partially - some errors are
acceptable) because Fresh have to build the tree of labels, defined in you program.

    Fresh does not use fixed pre-defined lists. It uses the labels you defined in the source.

    This is the only possible solution, because Fresh is not committed to any particular OS or
platform. If you write Win32 program, you need Windows API and constants in the auto completion box.
If you write Linux program, you need all Linux constants and API functions.

    To open code completion, press *Ctrl+Space* shortcut. Then when you type, the content of the box
will be refreshed in order to correspond with the word you type.

    You can select suitable element from the list with *Up, Down, PgUp and PgDn* keys
and press *Enter* to insert it in the line.

    Auto competion list will open automatically when you type some existing in the list label
and then press *"."* in order to select local label.

    You can close the auto completion window with *ESC* key.

## Project categories

    How to move a file from one category to another in the project?

    Open the file in the editor. Select the category where you want it to be moved.
Click the right mouse button on the tab of the file in order to display the context menu.
Select "Add to project" function. It will remove the file from the old category and will
move it to the current selected category.

## Fast open files

    How to open the file specified in "include" or "file" directive?

    Place the caret on the line that contains file name and press Ctrl+Enter.
    Opening files this way, Fresh replace the directory aliases and/or environment 
variables in the filename.

    Files like `%lib%/%TargetOS%/MyFile.asm` will be opened correctly.

## Directory aliases

    How to set promptly the values of the environment variables?

    Fresh have very flexible system of environment variables handling. Actually I prefer to call them
"Aliase", because they are aliases of the directories or other text.

    You can define such aliases in three ways:

* As OS environment variable.

* As IDE-wide aliases in the Fresh IDE options dialog ("Options|IDE options|Aliases" menu).

* As Project-wide aliases in the project options (Project|Project options" menu or Ctrl+F12 shortcut)

    When exists alias defined several times, then the project aliases have higher priority, then
the IDE aliases and with lowest priority are the OS environment variables.

    Now on the topic: The project aliases allows rapid value change. In order to use this
feature, you have to define the alias with several values, delimited with "|" symbol.
The count of different values is not limited.

    One typical example is the alias %TargetOS% used in the FreshLib test project.
This alias may have as values the names of the OS, the project will be compiled for.
So, in order to switch quick from Win32 to Linux we can define TargetOS as "Win32|Linux".

    In this case, at the top of the project window appears popup menu, where you can select what of these
values to be used. Additionally, the panel "Settings:" will display currently selected values.

       [!alias][Alias fast change]

## Portable applications

    How to write portable assembly applications with Fresh IDE?

    Most people think that assembly language can't be portable. It is not the case. There are many
examples that assembly can be portable. It is only matter of the project design, not the language.

    In order to allow creating of portable applications, FreshLib was created. It is work-in-progress,
but even now it allows creating of small applications that can be compiled for Win32 and Linux platforms
without change of the source.

    Read the unfinished [FreshLibRef][FreshLib reference manual]
and check the sources of FreshLib in "Fresh/freshlib" directory of your Fresh IDE installation.
There is a working test project called TestFreshLib.fpr that I use to test different FreshLib features.

Also, you can create FreshLib projects from template engine. Choose "File|New Application" from the 
main menu or press *Shift+Ctrl+N* shortcut. 

In the dialog window, select the target directory and application template - 
"FreshLib portble console application" or "FreshLib portable GUI application", 
then click *"OK"* and new project will be created.

Press *Shift+Ctrl+S* to save all new created files (you can change the filenames to whatever you like).

Then you can compile your application to Linux or Windows executable file.

The latest development version of FreshLib can be downloaded from the [rep][repository] - *FreshLibDev* branch.

[FreshLibRef] 2_FreshLibDoc.htm

[rep] http://chiselapp.com/user/johnfound/repository/FreshIDE/
        
[!goto] _images/goto.png

[!procarg] _images/ProcArgumentsHint.png

[!code] _images/CodeCompletion.png

[!alias] _images/AliasFastChange.png

[!cross] _images/CrossReference.png

FreshLib reference
# Chapter 6 FreshLib reference

## Overview 

FreshLib is an assembly library aimed to ease the development of assembly
language applications, freely portable between different platforms,
such as Win32 or Linux.

The library is coded in [FASM][flat assembler] syntax
and is intended to be easily used within [Fresh IDE],
although it could be used for plain FASM development.

The library consists of two layers: one, that is OS dependent and
a second one that is OS independent. The OS dependent layer is very
small, in order to help porting it for different OSes. This layer
only makes interface to the core OS functions, such as memory allocations,
file access, drawing functions, simple window management etc.

The OS independent layer is responsible for the main application functionality
allowing creation of different kind of windows and controls, processing of the
system messages, work with dynamic strings, arrays and other data processing.

FreshLib is mainly intended for developing GUI applications, as they
are the most challenging to be ported across different platforms.
FreshLib is also created with visual programming in mind, so it contains
a flexible, event driven and OS independent template engine allowing
visual creation of application user interfaces.

FreshLib is in early development stage and probably will be changed
many times in order to reach their objectives: to be small, fast and
easy to use.

The main intention is to keep the bloat off the library, but containing
all necessary accessories for comfortable programming of a very wide
range of applications.

The architecture of FreshLib is open and it can be freely expanded
with other libraries without increasing the size of applications.
In other words, only those parts of the library that are effectively
used will be compiled on the final executable.

------------------------------------------------------------------------

## About this manual 

This manual is a "work in progress". Any
part of it can be changed at any time.

Of course, some of the libraries described in this document are more
stable and finished like the macro, system and data libraries. Therefore,
the chapters about these libraries are less likely to be changed.
Other libraries (like graphics and GUI), will be heavily modified
so the manual will be changed accordingly.


------------------------------------------------------------------------

## Structure of the library. 

FreshLib contains many code and macros libraries, structured hierarchically
and depending on each other. Here is shown a part of the library directory tree:
;begin
    freshlib/
        compiler/
            Linux/
            Win32/
        data/
            Linux/
            Win32/
        dialogs/
            Linux/
            Win32/
        ...
;end
The library is structured to support different platforms transparently.
You can see, that the tree consists of main sub-directories, that
contains OS independent libraries, separated by topics.
For example *system* subdirectory contains libraries for accessing system
resources such as memory, files, etc. *data* contains libraries for data
handling and so on.
Every topic directory have also several sub-directories, that contains OS
dependent code these directories are named after the platform they serve. 
(In this moment only Linux and Win32 OSes are supported).

------------------------------------------------------------------------

## Compiler setup for FreshLib use.

You can use any FASM compiler to compile applications that uses FreshLib.
In order to be compiled properly, FreshLib needs environment variables
named `lib` and `TargetOS` to be defined.

The variable `lib` contains the path to the main directory of FreshLib
and the variable `TargetOS` contains the target platform, the application
will be compiled for. The value of `TargerOS` is identical to the name of
OS dependent directories in FreshLib.

There are several ways these variables to be defined, depending on
the compiler you use [FASM], [FASMW] or [Fresh IDE].

1. These variable can be defined in the OS environment - see your OS documentation for details.
this approach is more universal - it works for all kind of FASM compilers. The main drawback is
that you have to use OS specific commands and probably will have to edit some system files.

1. Definition in the section `[environment]` of *"fasm.ini"* or *"Fresh.ini"* file, depending on the
IDE you are using. This approach works for both FASMW and Fresh IDE, but in Fresh, the same
effect can be done from inside the IDE. Besides, defined this way, the environment variables
becomes "global" - active for all projects compiled with FASMW or Fresh.

1. From inside Fresh IDE.

In Fresh IDE, the environment variables are named *alias*,
because they serve to provide short alias for the file paths. Two types of alias (environment variables)
lists are supported by Fresh: *global aliases* and *project aliases*. Global aliases are
defined in the IDE options dialog: *Options|IDE options|Aliases*. Here is the screenshot
of this dialog:

  [!_images/AliasesDlg.png][IDE options dialog, section "Aliases"]

The global aliases are active for every project compiled with Fresh and are stored in the Fresh.ini file,
inside the Fresh program directory.

Project aliases are defined in the Project options dialog: *Project|Project
options* or from the project manager, click on the button *Settings* at the top
and select *Project options*. The project options dialog is shown on the following screenshot:

  [!_images/ProjectOptions.png][Project based aliases can be edited in the project options dialog.]

The project aliases are stored inside the project file (.fpr) and they are project specific.

For FreshLib it is not important what list will be used, but it is
more convenient for `lib` variable to be defined in the global list
and for `TargetOS` variable to be defined in the project aliases. In such way
the common parameter (the place of the library) will be set once for all projects, and
the particular parameter (the target OS) will be set separately for every project.

Also, there is very convenient way of changing the value of project
aliases — if several values are specified in the project alias, separated
with `|` char (for example: `Win32|Linux`), Fresh will provide fast switching
between these values from the project manager options menu, as shown on the picture:

   [!_images/fastswitch.png][The aliases with more than one value will appear in the popup menu for fast changing.]

When Fresh searches for needed alias names, during the compilation, it searches first in the project
aliase list, then the global aliases and at the end, the OS environment variables. Of course, if
the alias is not found on these places, the compilation fails with error.


[FASM] http://flatassembler.net

[FASMW] http://flatassembler.net

[Fresh] http://fresh.flatassembler.net

[Fresh IDE] http://fresh.flatassembler.net

------------------------------------------------------------------------

## FreshLib compiling options 

FreshLib uses some options in order to set the behavior of the compiler and the 
different macro libraries.
These options are defined as a local constants of the label *"options."*
Here is a list:

[#options.FastEnter] `options.FastEnter` controls the behavior of the [#proc] macro.

When *options.FastEnter = 1* the procedure entry/leave code will be created with
faster, but bigger push ebp/pop ebp instructions.

When *options.FastEnter = 0* — enter/leave instructions are used.

[#options.ShowSkipped] `options.ShowSkipped` controls the information displayed during compilation.

When *options.ShowSkipped = 1* the compiler will display in the output window the procedures
that are not compiled because they are not used in the program.

[#options.ShowSizes] `options.ShowSizes` controls the behaviour of the DispSize macro.

When *options.ShowSizes = 0* the macro [#DispSize] will be disabled.

[#options.DebugMode] `options.DebugMode` controls the behaviour of the debug macros.

When *options.DebugMode = 1* the macros from [#simpledebug] library will generate debug code and
debug console will be created on running the application.

When *options.DebugMode = 0* these macros will not generate code and the debug console will not be
created.

------------------------------------------------------------------------

## FreshLib code conventions 

### Naming conventions 

1. The names prefixed with one or more underscores ("_") are not recomended for use by the user.
These are internaly used labels that can be changed later. More underscores in the prefix - 
more "internal" is the given identifier.

For example one underscore ( like this: `_AlmostPrivate`) means - "use it carefully". 

Three underscores (for example `___SomeVeryPrivateLabel`) means - don't use it at all. 
It is for internal use only and will be changed later!

2. The names are considered to be used with code completion editor - i.e. there is no long equal 
prefixes of the names, but there are short "class" prefixes.
For example most of the procedures in StrLib begin with "Str" prefix. 

3. In general, FreshLib uses [CamelCase] naming convention, with constants in lowerCamelCase and 
procedures in HigherCamelCase.

4. All local labels and procedure arguments are prefixed with dot — ".";

5. Almost all of the [#struct] and all of [#object] definitions are prefixed with "T" prefix — for 
example [#TTimer] or [#TButton]

6. The file names convention. All file names with extension `.inc` doesn't contain any code or
data definition. Only macro and constants definitions are permitted.

The files with '.asm' extension can define code and data. Although, the code and data in FreshLib
can exists in the compiled binary, only if they are used. Not used data or code, included in
the binary should be considered a bug.

[CamelCase]  http://en.wikipedia.org/wiki/CamelCase


### Register preserving convention

1. The rule is - preserve all you are using. All procedures in FreshLib preserves all registers, 
except these used for returning result values.

;quote
Note: There is some small retreat from this rule - in the object handling procedures, some register 
are preserved internaly, so the user may not preserve them in its code. See [#object.asm] library 
for details.
;end

2. CF is widely used for returning error status or boolean result. 
As a rule *CF=0* means no error; *CF=1* means error.

The use of CF is described always in the description of the respective procedures.

3. The procedures can return result in more than one register. As a rule, EAX is the result register 
for the most procedures, but sometimes other registers are used - in order to provide better 
interface for assembly programming.

For example number of procedures return X,Y values in EAX, EDX registers.

* EAX — commonly used for returning 32bit values;

* EDX — second choise - used together with EAX for 64 bit values, or as a second returned value.

* ECX — usually some count. For example if EAX returns pointer to some memory, ECX will contains the 
data size. See [#LoadBinaryFile] for example.

------------------------------------------------------------------------

## Using FreshLib

There are only two files, the user should include in order to use FreshLib. They are both located
in the "freshlib" directory, usually referred by %lib% directory alias.

These files are:

* `%lib%/freshlib.inc` - contains all macro and OS dependent equates definitions.

* `%lib%/freshlib.asm` - contains all code of FreshLib. Only the used code will actually be included
in the result binary.

The minimal application with FreshLib have following code:

;begin
include "%lib%/freshlib.inc"

@BinaryType GUI

include "%lib%/freshlib.asm"

start:
        InitializeAll

        ; Place your code here

        FinalizeAll
        stdcall Terminate, 0

@AllImportEmbeded
@AllDataEmbeded
;end

The macros [#@BinaryType], [#@AllImportEmbeded], [#@AllDataEmbeded] will be explained later in the 
next chapter.

------------------------------------------------------------------------
## Data definitions in FreshLib program

FreshLib uses advanced data definitions macros, that allows data definitions to be mixed with the 
code, but then to be grouped and inserted in the data section of the program.
This kind of definitions greatly improves the readability of the program, because keeps the data
near to the code that uses it. It is especially important on big projects where the code is spreaded
among multiply files.
There are two main types of data - uninitialized and initialized data.

The initialized data definitions are enclosed inside [iglobal], [endg] macros and the uninitialized 
data in [uglobal], [endg] macros. Inside these blocks you can use all FASM data definition directives
or any other valid FASM code. Note only, that in `uglobal` block only the size of the data matters, 
if you use some defined data, the values will be lost.

;begin
iglobal
  MyGlobalVar dd 123, 456, 789
endg

uglobal
  SomeUndefinedVar rd 1
  SomeArray        rb 256
endg

;end

Another useful macro is [text] (actually it is struc). It defines some string constant anywhere in
the source code. The string constant is later defined in the data section of the program.

When used data definition macros, the user should define the data section with the macro [@AllDataEmbeded] or
[@AllDataSection] somewhere at appropriate place in the program, where all data should stay.


------------------------------------------------------------------------


## FreshLib directory "compiler/"

This directory contains only one macro library: *"executable.inc"*

### "executable.inc" library 

This library defines the macros that are going to be used for creating the main structure of
the program. The implementation of these macros is OS dependent, as long as the type of the
executable file is OS dependent: PE for Win32 and ELF for Linux. The use of the library, however
is OS independent and is common for all supported OSes.
Depending on the value of `TargetOS` alias, the library will create PE executable or DLL
`(%TargetOS%='Win32')`, or ELF executable or shared library `(%TargetOS%='Linux')`

*NOTE:* Every of the macros from this library must used only once in the program.

--------------

[#@BinaryType] `macro @BinaryType type`

This macro sets the type of the executable. The argument `type` can accept one of the following
values: `GUI`, `console` or `DLL`.

This macro also begins the main code section of the executable and defines the entry label of the 
program. The entry label is fixed to `start:`.

For example, following code will tell the compiler to compile the program as a GUI application:
;begin
      include '%lib%/freshlib.inc'
      @BinaryType GUI
;end

--------------

[#@AllDataSection] `macro @AllDataSection`
[#@AllDataEmbeded] `macro @AllDataEmbeded`

These macros defines all data definitions in the program, defined in `uglobal` and `iglobal` blocks 
and the text constants defined using `text` macro.

@AllDataSection, defines the data in a separate program "section". The meaning of the "section" 
term is different, depending on TargetOS definition. In Win32 it is `section '.data' data readable writeable`. 
In Linux it is `segment readable writeable`

@AllDataEmbeded defines the data, embeded in the code section of the program (created by @BinaryType macro).

Only one of these macros must be used. Usually @AllDataEmbeded will create smaller executable, although
some negative effects are possible, because embeded data and code is often considered "bad practice"

--------------

[#@AllImportSection] `macro @AllImportSection`
[#@AllImportEmbeded] `macro @AllImportEmbeded`

These macros automatically defines the import section of the program. This section is created
automatically depending on what functions was used in the program. 

Similar to the data section macros, @AllImportSection will create this data as a separate section, 
while @AllImportEmbeded will try to embed this data in the code section. 
(NOTE: In ELF executable format, the import data must be in separate segment, so
on TargetOS=Linux @AllImportSection and @AllImportEmbeded are equal.)

If embeded import section is used together with embeded data section, the import section should be
defined before the data section, because of undefined data definitions, that must reside at the end 
of the section (code section in the case of embeded data).

------------------------------------------------------------------------

## FreshLib directory "equates/"

[#allequates.inc] *"allequates.inc"* library. This library defines all
constants and structures needed for OS dependent parts of FreshLib.

Actually, the user should never use these constants and structures in the portable program.

The constants and structures that the user should use are defined in the respective libraries,
not in *"allequates.inc"*.

This library will be included automatically by "%lib%/freshlib.inc" file, so the user should not care
about this library at all.

------------------------------------------------------------------------

## FreshLib directory "imports/" 

[#allimports.asm]Another directory that contains only OS dependent definitions is *"imports/"* with a library
file to be included in the project: *"allimports.asm"*

This file is automatically included in the [#@AllImportSection] and [#@AllImportEmbeded] macros.
Then it will generate the proper import section, depending on the target platform and functions used 
by the OS dependent parts of FreshLib.

FreshLib contains very big catalog of shared libraries for Windows and decent set of Linux
shared libraries. The import macros used by FreshLib includes in the import section of the
program, only the functions used by the program, so it will never define redundant import items.

The user must never call directly imported functions from inside a portable application, except if
the imported dynamic library is portable as well. (as sqlite3.dll, for example)

------------------------------------------------------------------------

## FreshLib directory "macros/" 

This directory contains several libraries that provides common convenience functions to be
used with big assembly projects. 

All these libraries will be included automatically in "%lib%/freshlib.inc" file.

There is no overhead including all these libraries, because there is no code to be generated, 
just macro definitions. 
There is a little delay in compile time but thanks to fasm's speed, it is barely noticeable.

Lets examine each one of these libraries.

### "_stdcall.inc" library 

In general this library provides ways of definition and invoking of the procedures with
argument passing through the stack. It supports STDCALL and CCALL calling conventions.

-------------------

[#proc] `macro proc name, [arg]`
[#begin] `macro begin`
[#endp] `macro endp`
[#return] `macro return`
[#cret] `macro cret`
[#locals] `macro locals`
[#endl] `macro endl`

These macros define a procedure, create a stack frame for the local variables and define
symbolic names for the arguments. The macro "proc" defines the global label "name" as a name
for the procedure. All arguments and local variables are defined as a local labels with regard
to the name of the procedure. That is why all arguments and local variables must have names
beginning with dot.

Between the line with *proc* and *begin*, any number of local variables can be defined.
The macro *begin* marks the begining of the procedural code.

The macro *endp* marks the end of the procedural code.

The return from procedure instruction is provided by macros *return* or *cret* depending on
the calling convention we want to use: *return* clears the arguments from the stack and *cret*
does not.

Inside the procedure, a secondary stack frame can be allocated with the pair *locals* and *endl*.
All data definitions, enclosed between these macros will define a secondary stack frame that
is a continuation of the stack frame defined between *proc* and *begin*.

Any number of *locals* and *endl* pairs can be used, but all of these secondary stack frames
will overlap between each other. This feature is specially intended to provide savings of stack
space and at the same time, to provide talking variable names for the different parts of more
complex procedures.

For example (in Win32) let we have complex window procedure that have to process
multiple messages. 

One of the message handlers may need one variable `.rect`.

Another message handler may need two variables called `.point1` and `.point2`.

But the procedure as a whole is never going to need all those variables at the
same time, because it process only one message at a time. On the other hand it
may need the variable `.ctrldata` for every message processed. The optimal solution
is to define the variables as shown in the following example:

;begin
    proc CtrlWinProc, .hwnd, .wmsg, .wparam, .lparam
    .ctrldata dd ?
    begin
        invoke GetWindowLong, [.hwnd], GWL_USERDATA
        mov    [.ctrldata], eax

        cmp    [.wmsg], WM_MESSAGE1
        je     .message1
        cmp    [.wmsg], WM_MESSAGE2
        je     .message2
        return

    .message1:
    locals
      .rect RECT
    endl
        ; do something.
        return

    .message2:
    locals
      .point1 POINT
      .point2 POINT
    endl
        ; do something. 
        return
    endp
;end

The assignment of the stack memory for the above example is shown in the table:
;table
(1, 2) Address

(3, 1) Stack frames
;-----------------------
Common

Locals 1

Locals 2
;-----------------------
EBP-20

--

.rect.left

.point1.x
;-----------------------
EBP-16

--

.rect.top

.point1.y
;-----------------------
EBP-12

--

.rect.right

.point2.x
;-----------------------
EBP-8

--

.rect.bottom

.point2.y
;-----------------------
EBP-4

.ctrldata

--

--

;end

;;begin
;;+---------+---------+--------------+-------------+
;;|         |           Stack frames               |
;;+ address +---------+--------------+-------------+
;;|         |  common |   locals 1   |   locals2   |
;;|:-------:|:-------:|:------------:|:-----------:|
;;| EBP-20  |         | .rect.left   |   .point1.x |
;;| EBP-16  |         | .rect.top    |   .point1.y |
;;| EBP-12  |         | .rect.right  |   .point2.x |
;;| EBP-08  |         | .rect.bottom |   .point2.y |
;;| EBP-04  |.ctrldata|              |             |
;;+---------+---------+--------------+-------------+
;;        Procedure local labels memory map.
;;end

As you can see, *.rect* occupies the same memory as *.point1* and *.point2*,
but *.ctrldata* is never overlapped and exists independently.

As a general rule, you have to use the definitions between "proc" and "begin" for local
variables that are used in every call of the procedure and separate locals/endl definitions
for variables needed for the particular branches inside the procedure.
This approach will always provide the optimal size for the locals stack frame.

--------------------

[#initialize] `macro initialize`
[#finalize] `macro finalize`

The macros "initialize" and "finalize" defines one special type of procedures that, during
compilation are registered in a two separate lists - one for "initialize" and one for
"finalize" procedures. Procedures defined with "initialize" and "finalize" must have no any
arguments.

After that, using the macros "InitializeAll" and "FinalizeAll", all these procedures can be
call at once. "initialize" procedures are call in the order of their definition and "finalize"
procedures in reverse order.

These macros provides standard and consistent way for initialization and the
finalization of the libraries and modules of the application.

FreshLib uses this mechanism and the user is free to use it also.


-------------------------


[#stdcall] `macro stdcall proc, [arg]`
[#ccall]   `macro ccall proc, [arg]`
[#invoke]  `macro invoke proc, [arg]`
[#cinvoke] `macro cinvoke proc, [arg]`

These macros call the procedures with STDCALL and CCALL calling convention.

`stdcall` macro pushes the arguments to the stack in reverse order and then call
the procedure with label *proc*. As long as the macro "stdcall" does not provide
any stack cleanup (this duty is assigned to the procedure) the arguments can be
pushed in free manner using, for example, separate push instructions for part of
the arguments and arguments in the stdcall line for the remaining arguments.
This can be very convenient in some cases. For example see the following source:
;begin
    stdcall CreateSomeObject
    push    eax
    stdcall DoSomething
    stdcall DeleteSomeObject
;end
Here, the procedure DoSomething changes the value of eax, so the handle is saved
in the stack. The procedure DeleteSomeObject needs one argument — a handle of
the object. But as long as the proper value is already in the stack, it is
mindless to pop the value and then to push it again. So the source calls
DeleteSomeObject without any arguments. The procedure knows the proper number
of arguments (one in this example) and clean the stack properly.

The standard (and wrong) approach is to pop the argument from the stack and then
to pass it to the procedure explicitly is the stdcall statement:
;begin
    stdcall  CreateSomeObject
    push     eax                ; save the handle.
    stdcall  DoSomething
    pop      eax                ; ??? Why ???
    stdcall  DeleteSomeObject, eax
;end
This source will generate the meaningless instructions sequence:
;begin
    pop      eax
    push     eax
;end
*invoke* macro is the same as "stdcall" with the only difference - it calls the procedure
indirectly ( `call [proc]` instead of `call proc` ).  This mechanism usualy is used to call
the functions imported from external dynamic linked libraries.
Of course, the imported functions can be call with `stdcall [someproc]` but the *invoke*
macro helps to better distinguish what procedures are imported and what are internal for the
program.

*NOTE:* The user should never use *invoke* in the portable programs, because such programs
never use directly OS dependent import functions.


*ccall* macro calls a procedure with CCALL convention. This means that the procedure returns
with simple "retn", without cleaning the parameters from the stack. Then "ccall" macro provides
instructions that remove the arguments from the stack.

Because ccall have to know the exact count of passed arguments, all arguments have to be passed
explicitly as a values in the ccall statement.
Tricks as described above will not work properly and leads to stack not properly cleaned after
the call.

"cinvoke" is the same as ccall, but using indirect call. The reason for existing of "cinvoke"
macro is the same as with "invoke" macro — better legibility of the source.

*About the calling conventions:* While all Win32 dynamic linked libraries uses STDCALL
convention, most (if not all) of Linux libraries uses CCALL convention.

*All code libraries of Fresh use STDCALL calling convention and it is platform independient.*

-------------------------------------------------------------------------------------

### "_globals.inc" library 

This library defines several macros intended to deal with data definitions.

Usually all data definitions have to be placed in special section of the
executable file. ([#_DataSection] in FreshLib). This is not very convenient, because the code
that process this data and the data definitions must reside in separate places of the source
code, and in most cases even in different files.

The idea of *"globals.inc"* macro library is to allow the data definition to be
described anywhere in the source code, but these definitions to be defined at
once, at the place the programmer wants - usually in the data section of the
program.

--------------------

[#uglobal] `macro uglobal`
[#iglobal] `macro iglobal`
[#endg] `macro endg`
[#IncludeAllGlobals] `macro IncludeAllGlobals`

*uglobal* begins block for undefined data definition. The block ends with *endg*
macro. Between "uglobal" and "endg" macro any count of data definitions can be
inserted.

Note that because uglobal block defines undefined data, it is only the labels
and the size of data that have meaning inside this block. Any data, defined with
data definition directive will not increase the size of the executable file, but will
be allocated when the executable is loaded in the memory.

The undefined data will be defined later at the place where "IncludeAllGlobals"
macro resides. In order to not increase the size of the executable file,
the undefined data is always placed at the end of all data definitions.

"iglobal" macro, again combined with "endg" defines initialized data. The data
defined in the block will be created at "IncludeAllGlobals" statement.

This block increases the size of the executable file, because it contains
sensible data, that have to be included in the file.

Actually, neither *uglobal*, nor *iglobal* blocks defines any data immediately.
Instead, the data definitions are stored in a list. The real definition occurs
later, when *IncludeAllGlobals* macro is invoked.
For this reason, *IncludeAllGlobals* must be placed in the source after all used
global data blocks.

The programmer should never use explicitely IncludeAllGlobals. This macro will be invoked
on [#@AllDataSection] or [#@AllDataEmbeded] macros use.

---------------------

[#text] `struc text [val]`

The macro *"text"* is actually a structure. It needs to be preceded by some label name.

This macro accepts string or number arguments. When it is invoked with string arguments,
it defines a zero terminated string constant, and also a local constant *.length*
equal to the length of the string without terminating zero. When invoked with number as argument,
*"text"* defines label at the address *val* and does not defines .length constant.

The *"text"* macro, the same way as *iglobal* and *uglobal*, simply stores string data for
defer definition. This definition, occurs in IncludeAllGlobals invocation.
Note that the real definition will be made only if the string is used in the program.
Not used strings will not be defined.

Look at the following example:
;begin
        myName text 'John',$20,'Smith'
;end
This code will define the data and constant labels following way:
;begin
        if used myName
          myName db 'John Smith'
          .length = $-myName
                 db 0
        end if
;end

Why to define separate macro for the strings and not to use the normal iglobal
block? At first, *text* macro defines a real data only if this data is used
somewhere in the source. This way is prevented bloating of the code with
unneeded data definitions.

;quote
Also, the macro "text" was planned to check the strings
content and to not define any string more than once. In the case of repetitive strings,
this macro should return the pointer to the already defined string constant.

In that case, it would be very convenient and harmless to use unnamed string constants
in the function calling macros - stdcall, ccall etc.

Unfortunately, regardless of the power of fasm macro language, this functionality
cannot be implemented. Or, more precisely, it can be implemented, but the
implementation is too slow for any real project use.

This ineffective implementation is still leaved inside the file *"_globals.inc"* -
commented block that defines macro with name "*InitStringList*". If someone have
ideas about fixing this problem, please send it to me!
;end

------------------

[#var] `macro var expr`

The macro *var* defines dword variable with a given value. The use is following:
;begin
        var MyVar = 1234
;end
The only differens from the usual use of *dd* directive is that the variable will be
defined only if used in the source.

Note that the variable is created at the place where *var* is used, so you need to place it
inside a *iglobal* block if you want it to be defined in the global data place.

---------------------

### "_struct.inc" library 

This library contains only two simple macros:

[#struct] `macro struct name`
[#ends] `ends`

*struct* macro is aimed to provide easy creation of data structures. The "struc"
directive in FASM is known to not create actual labels, but only the template
for the label definitions. So, we need to create an instance of the data
structure in order to have addresses and offsets of its fields.

But very often we don't have static data structure of the given type, but data
structure, pointed by some of the registers. In this case in order to use
offsets to the fields of the data structure, we need to define at least one
virtual instance of the structure at address 0. Then we can use the values of
the fields as an offsets in the instructions - for example:
;begin
    mov eax, [esi+RECT.right].
;end
So, this is exactly what "struct" macro does. Besides it defines the "struc"
structure with the given fields, it creates a single virtual instance of this
structure, in order to be used later for register addressing.
Also, the macro defines local constant of *sizeof.* global label equal to the
byte size of the structure.
In all remaining functionality it behaves exactly as the struc directive.

The syntax of struct macro is the following:
;begin
    struct StructureName
      .field1 dd ?
      .field2 RECT
      .fieldN:
    ends
;end
The definition begins with "struct" followed by the structure name.
The definition ends with "ends" directive. Between both, any local label
definition becomes a member of the structure.
The above definition, results in following code:
;begin
    struc StructureName {
      .field1 dd ?
      .field2 RECT
      .fieldN:
    }
    virtual at 0
      StructureName StructureName
      sizeof.StructureName = $
    end virtual
;end

--------------------------------------------------------------

### "_display.inc" library 

This library contains macros that enhance the functionality of standard FASM
"display" directive.


[#disp] `macro disp [arg]`

The macro "disp" displays the strings given in the arguments, just as "display"
FASM directive does. Additionally it can display numbers in any given radix:
;begin
    disp <number, radix>
;end

---------------

[#DispSize] `macro DispSize Text, Sz`

"DispSize" is very specialized macro, that displays the text and number in
the following form:
;begin
Size of [Text] is: Sz bytes
;end
The size number is automatically scaled to bytes or kbytes, depending on the
value of Sz.

This macro allows easy display and control of the sizes of particular areas of
the program - data structures, subroutines etc.

DispSize macro behavior is controlled by [#options.ShowSizes] option.

-----------------

[#display] How Fresh implements "display" directive

There are some specifics in Fresh, concerning message displaying. The "display"
directive in Fresh works in a slightly different way than the original FASM directive.

It outputs text in Fresh message window. Each message can have one of six icons,
or it can have no icon at all. And because message window is implemented as a
TreeView control, you can organize your messages into groups (directories).

Implementation is a bit "tricky" - when you display a character whose code is
less than 16, it is interpreted in a special way. Characters from 1 to 6 set an
icon of current message. It sounds complicated, but it is quite simple. Try:
;begin
    display 2, "some message"
;end
It will display "some message" with an error icon. Another codes are used for
controlling directory structure. Try to type following lines and see what would
happen:
;begin
    display 3, "message at root", 0x09
    display 3, "child message1", 0x0a
    display 3, "child message2", 0x0d
    display 3, "again at root", 0x0a
;end
Of course you don't have to put each message in separate display directive, you
can, with the same result write:

display 3, "at root",$09,3,"child1",$0a,3,"child2", $0d,3,"again at root",$0a

Here is the complete list of all special characters and their meanings:
;table
char

meaning

note
;-------------
$01

set current icon to "warning"

 [?_images/warning.gif]
;------------------
$02

set current icon to "error"

 [?_images/error.gif]
;-----------------
$03

set current icon to "info"

 [?_images/information.gif]
;----------------
$04

set current icon to "find"

 [?_images/find.gif]
;----------------
$05

set current icon to "none"

--
;----------------
$06

set current icon to "debug" 

 [?_images/debug.gif]
;----------------
$08 

end current row and set one level back.

--
;----------------
$09

end current row and set it as new directory.

--
;----------------
$0a

end current row and keep current level.

--
;----------------
$0d

end current row and set current level to root level.

--
;end


;;begin
;;+------+--------------------------------------------------------+
;;| char |   meaning                                              |
;;|:----:|:-------------------------------------------------------|
;;| $01  |   set current icon to "warning"                        |
;;| $02  |   set current icon to "error"                          |
;;| $03  |   set current icon to "info"                           |
;;| $04  |   set current icon to "find"                           |
;;| $05  |   set current icon to "none"                           |
;;| $06  |   set current icon to "debug"                          |
;;| $08  |   end current row and set one level back.              |
;;| $09  |   end current row and set it as new directory.         |
;;| $0a  |   end current row and keep current level               |
;;| $0d  |   end current row and set current level to root level  |
;;+------+--------------------------------------------------------+
;;          display directive special characters
;;end


-------------------


## FreshLib directory "system/" 


-----------------


### "memory.asm" library 

This library provides OS independent way of allocating, reallocating and freeing
dynamic memory blocks.
All other libraries in FreshLib that needs dynamic memory, use this library.

The user who needs such memory blocks should use it as well.

--------------

[#GetMem] `proc GetMem, .size`

Allocates `[.size]` byte of dynamic memory.

Returns:

 `CF=0`; EAX = pointer to the allocated memory;

 `CF=1`; EAX=0 if the memory can not be allocated.

The memory is filled with NULL.

------------------

[#FreeMem] `proc FreeMem, .ptr`

Frees the specified in `[.ptr]` dynamically allocated memory.
Returns nothing.

-------------------

[#ResizeMem] `proc ResizeMem, .ptr, .newsize`

Reallocates memory on address `[.ptr]` to the new size in `[.newsize]`

Returns:

CF=0; EAX = pointer to the allocated memory;

CF=1; EAX=`[.ptr]` if the memory can not be reallocated.
In this case, the memory block is not changed

The increased part of the memory block is not zeroed.

-----------------


### "files.asm" library 


[#FileOpen] `proc FileOpen, .filename`

The procedure opens the file with filename in `[.filename]` for reading.

Returns:

`CF=0`; EAX = Handle to the file.

`CF=1`; EAX = Error code.

-------------------

[#FileCreate] `proc FileCreate, .filename`

Creates a file or opens the existing one and truncates its size to 0. The file is opened for writing.

Returns:

`CF=0`; EAX = Handle to the file.

`CF=1`; EAX = Error code.


----------------------

[#FileClose] `proc FileClose, .handle`

Closes the previously opened file.

Returns:

`CF=0`; EAX = Handle to the file.
`CF=1`; EAX = Error code.

----------------------

[#FileRead] `proc FileRead, .handle, .buffer, .count`

Reads `[.count]` bytes from the file `[.handle]` in the buffer at `[.buffer]`.

Returns:

`CF=0`; EAX = The count of actually read bytes.
`CF=1`; EAX = Error code.

---------------------

[#FileWrite] `proc FileWrite, .handle, .buffer, .count`

Writes `[.count]` bytes from the buffer `[.buffer]` to the file with handle `[.handle]`.

Returns:

`CF=0`; EAX = The count of actually written bytes.

`CF=1`; EAX = Error code.

------------------------

[#FileSeek] `proc FileSeek, .handle, .dist, .direction`

Moves the file pointer of the file `[.handle]` on `[.dist]` distance (in bytes) relative to `[.direction]`.

Direction is one of the following values:

`fsFromBegin` — relative to the file begin.

`fsFromEnd` — relative to the file end (then `[.dist]` should be negative).

`fsFromCurrent` — relative to the current position.

[#FileDelete] `proc FileDelete, .filename`

Deletes the file with filename in `[.filename]`

Returns:

`CF=0`; The file was deleted.
`CF=1`; EAX = Error code.

--------------------------

[#GetErrorString] `proc GetErrorString, .code`

Returns in EAX, pointer to the human readable error message, corresponding to the error code
passed in `[.code]`

The message string have to be passed to FreeErrorString, when not needed.

---------------------------

[#FreeErrorString] `proc FreeErrorString, .ptrString`

Frees the error string `[.ptrString]`, previously returned by GetErrorString. As long as the
error strings are allocated by the OS, they have to be free by OS as well.
Returns nothing.

--------------------------

[#LoadBinaryFile] `proc LoadBinaryFile, .ptrFileName`

Loads the whole file `[.ptrFileName]` to the dynamically allocated memory block.

Returns:

`CF=0`; EAX = pointer to the allocated memory; ECX = the size of the loaded file.

`CF=1`; EAX = Error code. ECX = 0; The memory is not allocated.

The allocated memory have to be free after use with [#FreeMem].

---------------------------

[#SaveBinaryFile] `proc SaveBinaryFile, .ptrFileName, .aptr, .size`

Creates or overwrites the file `[.ptrFileName]` with the `[.size]` bytes from the buffer `[.aptr]`;

Returns:

`CF=0`; EAX = count of the bytes actually write;
`CF=1`; EAX = error code;

--------------------------

[#FileExists] `proc FileExists, .ptrFileName`

Check the existence of the file with name in `[.ptrFileName]`.

Returnds:

`CF=1` — the file *does not* exists.
`CF=0` — the file exists.

The existence of the file is checked using [#FileOpen] procedure.
If the file can be opened, it is considered existing.

-----------------

### "process.asm" library 


[#Terminate] `proc Terminate, .exit_code`

Terminates the application and all of its threads.
Returns `[.exit_code]` to the OS.

This procedure simply does not returns, because the application stops.

----------------------

[#ThreadCreate] `proc ThreadCreate, .ptr_to_function, .ptr_to_args`

Creates new thread. `[.ptr_to_function]` points to the thread procedure.
The thread procedure should have one argument.
When the thread starts, `[.ptr_to_args]` is passed as a thread argument.

Returns:

`CF=0`; EAX = is a handle to the new thread. In the different OSes this value can have different meaning.
But it identifies the thread anyway.

`CF=1`; EAX = error code;

------------------------

[#MutexCreate] `proc MutexCreate, .ptrName, .ptrMutex`

Creates new mutex with name `[.ptrName]` and save its handle to `[.ptrMutex]` variable.

The calling thread takes the owneship of the mutex.

If `[.ptrName]` = 0, unnamed mutex will be created.

------------------------

[#WaitForMutex] `proc WaitForMutex, .ptrMutex, .timeout`

Waits until the mutex is released and takes the ownership.

Returns:

`CF=0` — the mutex ownership is successfuly obtained.
`CF=1` — the timeout was expired.


[#MutexRelease] `proc MutexRelease, .ptrMutex`

Releases the ownership of the specified mutex.

-----------------------

[#MutexDestroy] proc MutexDestroy, .ptrMutex

Destroys the mutex `[.ptrMutex]`

-----------------

### "clipboard.asm" library 

[#clipboard.asm] clipboard.asm library contains very simple clipboard functions that 
works only on text data.

------------------

[#ClipboardRead] `proc ClipboardRead`

Returns in EAX handle to the string with the current clipboard content.
If the clipboard is empty or contains not textual information, EAX=0;
The user should delete the string when not needed by passing it to [#StrDel].

--------------------

[#ClipboardWrite] `proc ClipboardWrite, .hstring`

Writes the string `[.hstring]` to the clipboard.
Returns nothing.

-----------------

## FreshLib directory "timers/" 


### "timers.asm" library 

[#timers.asm] library deals with user created timers and also contains some 
procedures for work with the system time and date.

------------------------------------

[#TTimer] `TTimer` structure.

The timers in FreshLib are represented with the following memory structure:
;begin
    struct TTimer
      .next dd ?

      .interval dd ?
      .value    dd ?


      .flags    dd ?
      .Callback dd ?
      .Expired  dd ?
      .tag      dd ?
    ends
;end
The fields are:

  * `.next` —  Don't change this. It is a pointer to the next timer in the timers chain. It is for internal use only.

  * `.interval` — the interval of the time in ms

  * `.value` — The current value of the timer in ms. When this value becomes higher than `[.interval]` an event is 
fired and the value becomes 0. This value is incremented by the system dependent time step - probably something like 1..100ms

  * `.flags` — contains a set of tmfXXXX flag values. Determines the behavior of the timer. See below for description of the flags.

  * `.Callback` — pointer to the callback procedure of the timer.
                  The callback procedure should accept one argument with the pointer to the timer that fired the event: `proc OnTimer, .ptrTimer`

  * `.Expired`  —  count of the timer expirations, if the callback procedure was not called.

  * `.tag`  —  user defined value associated with the timer.


The `.flags` field can have one or more of the following values:

 * `tmfDoNothing`  — when the timer expires no action should be performed. .Expired field of the timer will be incremented.

 * `tmfCallProc` —   `[TTimer.Callback]` contains pointer to the procedure that to be executed once per timer expiration.

 * `tmfSyncDestroy` — If this flag is set, the timer will be destroyed on the next timer expiration.
                      In this case, the configured event is fired and then the timer is destroyed.
                      The flag is checked after the event returns, so the event handler can reset this flag and thus to prevent destruction.

 * `tmfRunning` — If this flag is set, the timer runs. If the event handler resets this flag, the timer will fire only once and will be suspended.

-----------------------

[#TimerCreate] `proc TimerCreate`

Creates a new timer.

Returns:

 * CF=0; EAX= pointer to the TTimer structure. The timer is created suspended.
         The user can set or reset tmfRunning in `[.flags]` in order to start or stop the timer.
         Also, the user have to enter proper values in the remaining fields.

 * CF=1; Error allocating memory.

---------------------- 

[#TimerDestroy] `proc TimerDestroy, .ptrTimer`

Destroys the timer `[.ptrTimer]`

------------------


## FreshLib directory "simpledebug/"

### "debug.asm" library 

[#simpledebug] This library includes number or macros and procedures aimed to assist the debugging
process of the application. These macros display different data values on the debugging
console.

The library contains its own output procedures, so it does not depend on the other used libraries.

All the macros from this library generate code only when [#options.DebugMode] = 1, so the
programmer can include as many debug statements as needed and leave them in the source.
They will not be included in the final binary.
The debug macros will always preserve all registers, except the EFLAGS register.

-------------

[#DebugMsg] `macro DebugMsg msg`

Displays the text message `msg` to the debug console.
Example:
;begin
     DebugMsg 'The program executes here!'
;end

----------------

[#OutputRegister] `macro OutputRegister reg, radix`

Outputs the content of some register in the given radix. Example:
;begin
    OutputRegister regEAX, 10
;end
The possible register values are: `regEDI`, `regESI`, `regEBP`, `regESP`, `regEBX`, `regEDX`, `regECX`, `regEAX`

----------------

[#OutputMemory] `macro OutputMemory pointer, size`

OutputMemory will dump `[size]` bytes of memory at address `[pointer]`; Example:
;begin
    OutputMemory esi, 128
;end

---------------

[#OutputNumber] `macro OutputNumber number, radix, digits`

Outputs *digits* digits of the *number* in *radix* radix. Example:
;begin
    OutputNumber 12345, 16, 8
;end

------------------

[#GetTimestamp] `proc GetTimestamp`

Returns in eax timestamp measured in milliseconds (ms).

-----------------


## FreshLib directory "data/" 

This directory contains several libraries that handles different data structures.
The libraries are mostly OS independent.
Actually the only OS dependent part is one small routine in Win32 section, that
converts strings from UTF-8 to UTF-16 because Windows can't handle UTF-8 strings
directly.

------------------

### "arrays.asm" library 

This library handles dynamic arrays, containing elements of arbitrary size.
All elements of the array have the same size.

[#TArray] TArray structure have following definition:
;begin
    struct TArray
      .count     dd ?
      .capacity  dd ?
      .itemsize  dd ?
      .lparam    dd ?
      label .array dword
    ends
;end
The above structure represents the header of the array. The actual array will
have arbitrary size, depending on the element count and size.

The first element of the array begins on offset *TArray.array* from the begining
of the memory block.

The field *TArray.count* contains the current element count of the array.

The field *TArray.capacity* contains the current capacity of the array.
It is because the library usually allocates more memory than is needed for the array
element count.
This approach reduces memory allocations and reallocations and
thus increases the speed of inserting and deleting elements in the array.
How many memory will be allocated depends on the user setting of the variable
ResizeIt (defined in memory.asm). This variable contains a pointer to the
procedure that simply increases the value of ECX to the next suitable value.

The field *TArray.itemsize* contains the size in bytes of one array element.
Changing of this value is not recommended.

The field *TArray.lparam* is for user defined parameter, associated with the array.

-----------------------------

[#CreateArray] `proc CreateArray, .itemSize`

This procedure creates new array with item size `[.ItemSize]`

The procedure returns CF=0 if the array is properly created and pointer to the
array is placed in EAX.

In case the memory cannot be allocated, the procedure returns CF=1.
To free the allocated array, use [#FreeMem] procedure.

------------------------------

[#AddArrayItems] `proc AddArrayItems, .ptrArray, .count`

This procedure adds new array items at the end of the array pointed by `[.ptrArray]`

The procedure returns two values:

EAX contains pointer to the first of the new appended elements.

EDX contains pointer to the array (in the process of appending of the new
element, it is possible the whole array to be moved to the new address in
memory, so the programmer should store the value of EDX for the future
reference to the array.

In case, the new memory can not be allocated, the procedure returns CF=1 and
EDX contains the proper pointer to the original array.

----------------------------------

[#InsertArrayItems] `proc InsertArrayItems, .ptrArray, .iElement, .count`

This procedure inserts `[.count]` new elements at the `[.iElement]` position of the
array pointed by `[.ptrArray]`

If `[.iElement]` is larger or equal to `[TArray.count]` the elements are appended
at the end of the array. (Just like AddArrayItems) Otherwise, all elements are
moved to make room for the new elements.

The procedure returns exactly the same results as AddArrayItems procedure — EDX
points to the array and EAX points to the first of the new inserted elements.

CF is an error flag.

---------------------------------

[#GetArrayItem] `proc GetArrayItem, .array, .item`

CF=0; Returns in EAX pointer to the array item with index `[.item]`.

CF=1; The requested item does not exists ( `[.item]` >= `[.array.count]` ). In this case,
EAX contains pointer to the end of the array the byte next after the last array element.

---------------------------------

[#DeleteArrayItems] `proc DeleteArrayItems, .ptrArray, .iElement, .count`

This procedure deletes `[.count]` items with begin index `[.iElement]` the `[.ptrArray]`
dynamic array. If the capacity of the array is bigger than the recommended for
the new count, then the array is resized. The recommended size is calculated
using ResizeIt procedure from memory library.

Returns EDX - pointer to the TArray. In the most cases this pointer will not be
changed, but this also depends on the current OS memory allocation API, so it
is safer to store the pointer for future use, instead of one passed to the
procedure.

This procedure can not fail, because deleting element is always possible. In
some rare cases it can fail to reallocate smaller memory block, but this is
not a problem for the array consistency.

---------------------------

[#VacuumArray] `proc VacuumArray, .ptrArray`

This procedure removes the reserved memory from the array in order to make it
as small as possible.
Note, that the first insert/append operation after the vacuum operation will be very slow.
The memory economized this way depends on reallocation strategy and can be from 25 to 100% in some cases.

--------------------------

[#ListIndexOf] `proc ListIndexOf, .ptrList, .Item`

The list is a special case of array with item size equal to 4 bytes (dword).
This procedure searches the list `[.ptrList]` for item equal to `[.Item]` and
returns the index of the element in EAX. In case of error CF=1.

---------------------------

[#ListFree] `proc ListFree, .ptrList, .FreeProc`

Frees all elements of the list `[.ptrList]`, calling `[.FreeProc]` for every
element of the list.

FreeProc callback procedure have one argument of type dword that is the value
of the current list element. The definition of the callback procedure is similar
to following:

;begin
    proc FreeMyListItem, .ptrItem
    begin
            ;do something with the item being freed
            return
    endp
;end


-----------------


### "strlib.asm" library 

[#StrLib]

Using strings in assembler was often problematic for programmers - static
strings can't be resized, so they had to reserve as many bytes as they thought
user could need, and it still could be not enough. For that reason we created
Dynamic String Library - a library that operates on dynamic strings, that are
automatically resized when needed. Also, StrLib contains many functions that
perform different string operations — comparison, inserting one string into
another, etc.
In StrLib, the strings are represented by handles, not by pointers. This way,
the string can be freely resized and moved in memory.
StrLib can distinguish the handle values from pointer and will process properly
both of them. When the processing is possible, the procedures will operate
on static strings in memory.

[#StrLib string format]

The strings in the StrLib are stored in specific format. The format is defined
following way:
;begin
    struc string {
      .capacity dd ?
      .len      dd ?
      label .data byte
    }

    virtual at -(sizeof.string)
      string string
      sizeof.string = $-string
    end virtual
;end
The structure string have variable length and is dynamically allocated.

The field *string.capacity* on offset `-8` contains the allocated memory size in bytes.

The field *string.len* on offset `-4` contains the current length of the string in bytes.

The string content begins on offset 0. The content of the string always ends with at least one
zero byte, so the string format is compatible with ASCIIZ format used in the most OS API.

All procedures in StrLib will set `[string.len]` to the proper value and will use it in the
string processing.

If the programmer manipulates the string data directly, he should set `[string.len]` himself, or
call [#StrFixLen] in order to let StrLib to scan the string and to fix the length field.


[#StrLib procedures]

StrLib procedure reference:

[#StrNew]
;begin
        proc StrNew
;end
Creates new dynamic string and returns its handle.

[#StrDel]
;begin
        proc StrDel, .hstring
;end
Frees the memory occupied by given string. If the .hstring is pointer to memory, StrDel
will try to find it in the table of created strings and if found, will free it as well.
If the string passed by pointer is not found in the list - StrDel exits without error.
Note, that passing pointer can degrade the performance of the procedure.

[#StrPtr]
;begin
        proc StrPtr, .hstring
;end
Returns in EAX the pointer of the string with handle `[.hstring]`
If .hstring is pointer EAX will be equal to `[.hstring]`
If the handle is invalid, StrPtr returns CF=1 and EAX=0.


[#StrLen]
;begin
        proc StrLen, .hstring
;end
Returns the length of the string in bytes, excluding the terminating zero.
If `[.hstring]` is handle, the procedure returns directly the stored length of the string.
If `[.hstring]` is pointer, the functions scans the string and computes the length.
Thus, passing handle is much faster, especially for long strings.


[#StrDup]
;begin
        proc StrDup, .hstring
;end
Creates new string and copy the content of `[.hstring]` to it.
Returns in EAX — handle of the new string.
`[.hstring]` can be memory pointer or string handle.



[#StrFixLen]
;begin
        proc StrFixLen, .hstring
;end
StrFixLen scans the string in order to compute its actual length and then writes this length
in the field `[string.len]`.
StrFixLen should be call only with handle of the string as argument. It will process pointer as
well, but will assume there is a field `[string.len]` at offset `-4`.
The user should call StrFixLen only if the `[string.len]` field does not contains the proper value,
because of some reason - for example the user made some string processing that changes the length
of the string or the string data is returned by some OS function that does not care about string
length.


[#StrSetCapacity]
;begin
        proc StrSetCapacity, .hString, .capacity
;end
This function ensures that the allocated for the string memory is enough to hold at least
`[.capacity]` bytes. If needed the string memory is reallocated.
Returns pointer to the string data in EAX.
If the reallocation is impossible, returns CF=1;


[#StrCopy]
;begin
    proc StrCopy, .dest, .source
;end

Copies the content of `[.source]` string to `[.dest]` string.
`[.dest]` must be a handle.
`[.source]` can be handle or pointer.
Returns nothing.



[#StrCompCase]
[#StrCompNoCase]
;begin
    proc StrCompCase, .str1, .str2
    proc StrCompNoCase, .str1, .str2
;end
Compares two strings - case sensitive (StrCompCase) or string not sensitive (StrCompNoCase).

Returns CF = 1 if the strings are equal.

Returns CF = 0 if the strings are different.

The speed of this procedure varies depending on passed strings and its content.
The worst case is when the strings are passed as pointers and have equal lengths.
The best case is when the strings are passed as handles and have different lengths.


[#StrCat]
;begin
    proc StrCat, .dest, .source
;end
Concatenates the string `[.source]` to the end of the string `[.dest]`.

[#StrCharPos]
;begin
    proc StrCharPos, .hString, .char
;end
StrCharPos returns a pointer to the first occurence of a given char in specified string.

[#StrPos]
;begin
    proc StrPos, .hstring, .hpattern
;end
StrPos returns in EAX a pointer to the first occurence of a `[.hpattern]` string in
`[.hstring]` or NULL if the pattern was not found.


[#StrCopyPart]
;begin
    proc StrCopyPart, .dest, .source, .pos, .len
;end
Extracts `[.len]` bytes on position `[.pos]` from the string `[.source]` and copies them
to the string `[.dest]`.
Returns CF=1 if the needed memory can not be allocated.


[#StrExtract]
;begin
    proc StrExtract, .string, .pos, .len
;end
Extracts `[.len]` bytes on position `[.pos]` from the string `[.source]` and copies them
to the new created string.
Returns the created string in EAX or CF=1 if the needed memory can not be allocated.


[#StrSplit]
;begin
    proc StrSplit, .hString, .pos
;end
Splits the string `[.hstring]` into two parts on byte possition `[.pos]`.
The left part remains in `[.hstring]`; The right part is returned as new created string in EAX.
Note that the memory of the `[.hstring]` will not be reallocated, only the length of the string
will be set accordingly.


[#StrInsert]
;begin
    proc StrInsert, .dest, .source, .pos
;end
Inserts the `[.source]` string on possition `[.pos]` into the `[.dest]` string.
Returns nothing.


[#NumToStr]
;begin
    proc NumToStr, .num, .flags
;end
Converts number `[.num]` in any radix to string.
Returns the new created string in EAX.

`[.flags]` controls the way number have to be converted.
.flags is dword value that contains following values:

byte0 - number of digits if ntsFixedWidth is specified.

byte1 - radix for the convertion. Some radixes have predefined constants:
;begin
    ntsBin  = $0200
    ntsQuad = $0400
    ntsOct  = $0800
    ntsDec  = $0a00
    ntsHex  = $1000
;end

byte2, byte3 - flags:
;begin
    ntsSigned       = $00000
    ntsUnsigned     = $10000
    ntsFixedWidth   = $20000
;end

[#StrToNumEx]
;begin
    proc StrToNumEx, .hstring
;end
Converts `[.hstring]` to number.
Returns CF=0 and value in EAX if the conversion was successful, or
CF=1 and EAX = 0 if not.

The procedure supports the FASM numbers format:

`0x1111`, `$1111` or `1111h` will be converted as HEX;

`1111` as decimal;

`1111b` as binary;

`1111o` as octal.


[#StrCharCat]
;begin
    proc StrCharCat, .hString, .char
;end
Appends up to 4 bytes fro `[.char]` at the end of `[.hString]`


[#StrCharInsert]
;begin
    proc StrCharInsert, .hString, .char, .pos
;end
Inserts up to 4 characters from `[.char]` into the `[.pos]` position of the `[.hString]`


[#StrClipSpacesR]
[#StrClipSpacesL]

;begin
    proc StrClipSpacesR, .hString
    proc StrClipSpacesL, .hString
;end

Removes the spaces from the start (StrClipSpacesL) or from the end (StrClipSpacesR)
of the string `[.hString]`.


[#StrCleanDupSpaces]
;begin
    proc StrCleanDupSpaces, .hString
;end
Removes duplicating spaces from the string `[.hStrin]` and leaves only single spaces.
For example the string ("." represents the space char) "123.....456" will be processed to "123.456".

[#StrHash]
;begin
    proc StrHash, .hString
;end
Computes the hash value from the string `[.hString]`.
This procedure implements FNV-1b algorithm.

Returns 32 bit hash value in EAX.


[#DataHash]
;begin
    proc DataHash, .ptrData, .len
;end
Computes the hash value from the memory array at address `[.ptrData]` with byte length `[.len]`.
This procedure also uses FNV-1b algorithm.

Returns 32 bit hash value in EAX.


[#StrLenUtf8]
;begin
    proc StrLenUtf8, .hString, .len
;end
Computes the length in chars of the first `[.len]` bytes of the UTF-8 encoded string `[.hString]`
The scan of the string ends on one of the two conditions — terminating zero byte
is reached or `[.len]` bytes are processed. So, if `[.len] == -1` the scan will always end on the
end of the string.


[#StrOffsUtf8]
;begin
    proc StrOffsUtf8, .hString, .pos
;end
Returns in EAX the address of the `[.pos]` character of the UTF-8 encoded string `[.hString]`
If the length of the string is less than `[.pos]` — returns NULL.


[#DecodeUtf8]
;begin
    proc DecodeUtf8, .chars
;end
Decodes 4 bytes in `[.chars]` to UNICODE dword value.

Returns:
`CF=0` — no error; eax — unicode value; edx — byte count of the char. `[1..4]`

`CF=1` — invalid utf-8 char; if eax = edx = 0;  the character can not be decoded;
if edx <> 0 — eax = the overlong encoded character. edx = byte count of the char.

*Note:* When CF=1 and `[.chars]` is overlong encoded char, eax contains the proper
value and edx contains the proper length. But it is still invalid character, according
to the standards.

[#ExpandTabs]
;begin
    proc ExpandTabs, .hstring, .tabstop
;end

Converts the tab characters in `[.hstring]` into space characters, according to `[.tabstop]` length.
Returns in EAX a value, that indicates by how many chars the length of the string increased.


-----------------


### "uConfig.asm" library 

uCongig library is implementation of small [hierarchical] database engine, intended to keep program settings and
preferences in OS independent manner.
The data in the uConfig database have tree structure similar to the file system directory structure
or to Windows registry structure.
Every record or directory in the database has its own key — dword value.
Usually it is convenient to use as a key 4 char ASCII string in order to be human readable, but
it is not mandatory.
;quote
The uConfig format is not "human readable", "universal", "super-puper", etc.
It was designed with only two aims:

1. Small and simple engine, suitable to be used from assembly.

2. Relatively robust database format.

So, if someone wants some new advanced features - these features should make the engine
smaller or at least to keep its current size.
;end

[hierarchical] http://en.wikipedia.org/wiki/Hierarchical_database_model

The database have two representations — packed "file representation" and
expanded "memory representation".
Database operations can be provided only on expanded form.

The base of the database is TConfigRecord structure. The database itself is an array of
TConfigRecords.

[#TConfigRecord]
;begin
    struct TConfigRecord
      .KeyName  dd ?
      .DataSize dd ?
      .Type     dd ?
      .Data     dd ?
    ends
;end
The fields have following meaning:

* .KeyName — contains the key of the record.

* .DataSize — the size of the data in bytes if .Data field contains pointer to the data.

* .Type is one of the following values:
;quote
*  cdtNULL     = 0
*  cdtInteger  = 1  — .Data contains the number.
*  cdtString   = 2  — .Data contains string handle (see [#StrLib])
*  cdtBlob     = 3  — .Data contains pointer to the blob data. .DataSize — its size
*  cdtConfig   = 4  — .Data contains pointer to the [#TArray] of TConfigRecords — i.e. uConfig database.
;end
* .Data — data value if fits in dword or pointer to the data for the bigger formats.

There are number of procedures intended to provide manipulation of uConfig database:

[#LoadCongigDB]
;begin
    proc LoadConfigDB, .ptrSource, .signature
;end
Loads the "file representation" of database and expands it to "memory representation".
".signature" is DWORD value, that identifies the database. The signature is actually 8 bytes long —
the first dword identify the file as a uConfig database and the second dword are user defined.

The procedure returns:

CF=0; EAX = pointer to the root level of the expanded database

CF=1; Database error:
;quote
EAX = `-1` : Bad signature

EAX = `-2` : Damaged database. Some control sum is wrong.
;end


[#SaveConfigFile]
;begin
    proc SaveConfigFile, .ptrRoot, .signature
;end
Creates "file representation" of the database as a memory TArray of dword. The user have to save
this image to the file if needed.

* .ptrRoot is pointer to TArray ot TConfigRecord.

* .signature if the desired signature for the database file.

The procedure returns pointer to TArray. The user should free it later.


[#FreeConfigDB]
;begin
    proc FreeConfigDB, .ptrRoot
;end
Frees the uConfig database and all its records.

[#GetConfigParam]
;begin
    proc GetConfigParam, .ptrConfig, .pDirectory, .name
;end
Search the database `[.ptrConfig]` for the record with keyname `[.name]`

Returns EAX = poiner to the TConfigRecord or NULL if the record is missing.

`[.pDirectory]` should point to the zero terminated array of dwords with the path to the directory
of the needed record. `[.pDirectory]` can be NULL.

[#GetConfigParam.AsString]
;begin
    proc GetConfigParam.AsString, .ptrConfig, .pDirectory, .name
;end
Returns handle to string with textual representation of the value of the database record.
The user have to free this string later with [#StrDel].
This procedure is intended to be use for screen display of the values of the database.
Depending on the type of the field it returns:

 *  cdtNULL — "NULL"

 *  cdtInteger  — The number converted to decimal string.

 *  cdtString   — A copy of the string.

 *  cdtBlob — "BLOB"

 *  cdtConfig  — "SDIR"


[#DelConfigParam]
;begin
    proc DelConfigParam, .ptrVarConfig, .pDirectory, .name
;end
Deletes the specified config record. Returns nothing.



[#SetConfigParam]
;begin
    proc SetConfigParam, .ptrVarConfig, .pDirectory, .name, .type, .value, .size
;end
Set the value of the given config record. If the record exists, the value will be changed.
If the record with the given name does not exists, it will be created.
Returns error in CF. If CF=1 the specified directory does not exists.



-----------------


### "memstream.asm" library 


-----------------


## FreshLib directory "graphics/"

The graphics library provides procedures that draw graphics images and text on
the screen. The library is OS dependent and is placed in the directory
"graphics" in the root directory of FreshLib.

The main conception of this library is ".raster" - represented by handle
object, where the drawing happens. 

The exact meaning for this object is
different for the different OSes — in Win32 it is named "device context", in
Linux it is "drawable" - window or pixmap.

--------------------

### "context.asm" library 


--------------------

### "draw.asm" library 

--------------------

### "fonts.asm" library 

--------------------

### "text.asm" library 

--------------------

### "images.asm" library 

--------------------

### "giflib.asm" library 

--------------------

### "backbuffer.asm" library 

--------------------

## FreshLib directory "mouse/" 

-------------------

### "mouse.asm" library 

------------------

## FreshLib directory "GUI/" 


This directory contains the libraries providing portable GUI for assembly
programming.

Note that these libraries are in very early stage of development, so the
description in this chapter is preliminary and probably will be changed in
one or another way in the near future.

The main idea behind the GUI library is to make one small OS dependent layer of
functions, that to serve as an interface between the OS and the OS independent
layer of the library.

The first will translate OS events, such as mouse, keyboard, timers etc to one
common standard of OS independent event handlers of the user interface
objects — windows, buttons and other widgets.

The biggest advantage of this approach is that the porting of the library
is very easy — most of the code is OS independent and only little part of it
have to be rewriten in order to port the whole library to a new OS.

The biggest drawback of this approach is the bigger size of the library,
because, with this architecture, all controls in the library have to be created
from scratch. It is impossible to use graphic controls that the OS provides —
particularly Win32 controls - buttons, simple text editors, labels, combo boxes
list and tree view controls etc.

This library is not aimed to use all complex GUI system of the target OS.
At first time, the goal of Fresh GUI library is to provide minimal, but decent
functionality that will do the job — writing portable GUI applications in
assembly language.

The GUI library is actually set of libraries.
These libraries defines many data structures and procedures that together, form
something that conditionally can be called "Object oriented" environment.
It is object oriented, as long as it deals with GUI "objects" - forms,
controls, menus etc.

On the other hand, the library does not limit the programmer in the way HLL OOP
limits him. The user have full access to all data structures of the program.
The "encapsulation" principle is fairly impossible in the assembly programming.

All objects in Fresh GUI library, are in fact structures of data.
For every created object, the library allocates some memory and fills this memory
with object parameters data.

There are two types of data structures that describe GUI objects - classes and
instances.

The *class* is a structure that contains data commonly used by all objects of
given type — for example all buttons use one class structure `CButton`.

*Instance* is a data structure that describes the properties and behavior of
particular GUI object — for example button with icon "open file" that opens
a file when the user click on it.

### Classes 

[#class]

*"Class"* in FreshLib is a data structure, that have the following definition:
;begin
    struct TObjectClass
      .ptrParent           dd 0
      .dataSize            dd 0
      .procCreate          dd 0
      .procDestroy         dd 0
      .procGetParam        dd 0
      .procSetParam        dd 0
      .procExecCmd         dd 0
      .procSysEventHandler dd 0
    ends
;end
`.ptrParent` is a pointer to other TObjectClass structure, that appears as a
parent class for the given class.

`.dataSize` contains the size in bytes of the object instance structure.

The following fields are pointers to procedures that provides the "engine"
of the object. All of these pointers as a rule can be NULL, if there is no need
for such processing.

[#.procCreate]

`.procCreate` is a pointer to procedure that creates instance object of the given class.
This field can be NULL. It has the following definition:
;begin
    proc Create, .obj
;end
This procedure sets needed values in the object instance data structure.

*Note:* This procedure does not allocate any memory. The needed memory block is allocated by
the [#objects] library and the pointer to this allocated block is passed to this procedure in the
argument `.obj`.

[#.procDestroy]

`.procDestroy` is a procedure that destroys an instance of the given class.
;begin
    proc Destroy, .obj
;end
Frees the memory, images, fonts and other resources, allocated for the object `.obj` during
its existence. Must not free the object itself.


[#.procGetParam]

.procGetParam is a pointer to the procedure that retrieves and returns the properties of the object.
;begin
    proc GetParam, .obj, .paramID
;end
Returns the value of the object `[.obj]` parameter with ID=`[.paramID]`

[#.procSetParam]

.procSetParam is a pointer to the procedure that set the properties of the object.
;begin
    proc Set, .obj, .paramID, .value
;end
For object `[.obj]`, set the value of the parameter with ID=`[.paramID]`


[#.procExecCmd]

.procExecCmd is a pointer to the procedure that executes object method.
;begin
    proc ExecCmd, .obj, .method
;end
For the object `[.obj]` this procedure executes the method with ID in `[.method]`.

The methods can have arbitrary number of arguments, that are defined in the
 [#object] definition (see below). When the method is executed, the procedure
`[.procExecCmd]` accepts pointer to the arguments array in the register EBX.

The user is supposed to call methods of the object with the macro "execute"
The macro is defined following way:

[#execute]
;begin
    macro execute obj*, meth*, [arg]
;end

[#.procSysEventHandler]

.procSysEventHandler is a pointer to the procedure that process the system
events that are send to the object, i.e. mouse events, keyboard events etc.
;begin
    proc SysEventHandler, .obj, .pEvent
;end
Process one system event for object `[.obj]`. `[.pEvent]` contains pointer to the
system event.

All of the above callback procedures are called internally and should not be
used by the user of the library. How these procedure are called will be described later.

TObjectClass structure is defined statically in memory, in compile time, only
once for every object class. Its definition is located in the library for the
respective GUI element. For example CButton class structure is defined in the
file TButton.asm that contains the code and data of the object class Button.

In order to make construction of such structures easy, macro with name
ObjectClass is defined in objects.asm

[#ObjectClass]
;begin
    macro ObjectClass name*, parent*,   \
                      procCreate*,      \
                      procDestroy*,     \
                      procGetParam*,    \
                      procSetParam*,    \
                      procExecCmd*,     \
                      procSysEvents*
;end
Every defined ObjectClass have a label that points to the begin of the structure.
The name of this label is the name of the class, prefixed with "C".

One example of ObjectClass definition is the definition of Window object class:
;begin
    ObjectClass Window, Object,     \
                TWindow.Create,     \
                TWindow.Destroy,    \
                TWindow.Get,        \
                TWindow.Set,        \
                TWindow.ExecCmd,    \
                TWindow.SysEventHandler
;end

This definition creates following data structure in the memory:
;begin
    CWindow:    dd  CObject
                dd  sizeof.TWindow
                dd  TWindow.Create
                dd  TWindow.Destroy
                dd  TWindow.Get
                dd  TWindow.Set,
                dd  TWindow.ExecCmd
                dd  TWindow.SysEventHandler
;end

### Object instance structure

[#object]
[#endobj]
[#instance]

Object instance is data structure that contains different fields. By that it is
very similar to the normal FASM structures. As structures, the object is only
description of the data but not the data itself.

Objects can inherit field definitions by its parent objects. The memory instance
of the object is allocated dynamically in runtime, when the object is created
by call to the respective FreshLib procedures.

The definition of the object looks like following:
;begin
    object TObject
      .ptrClass     dd ?

      .mxAccess     dd ?
      .ptrVar       dd ?

      .OnCreate     dd ?
      .OnDestroy    dd ?

      method .AddChild, .objchild
    endobj

    object TWindow, TObject
      .handle       dd ?
      .Fcaption     dd ?
      .Fcursor      dd ?

      param .x
      param .y
      param .width
      param .height
      param .visible
      param .caption
      param .parent
      param .cursor

      method .Refresh
    endobj


    object TButton, TWindow
      .state      dd ?
      .Ficon      dd ?
      .FiconAlign dd ?
      .Ftextalign dd ?

      .OnClick dd ?

      param .TextAlign
      param .Icon
      param .IconPosition
    endobj
;end

By convention the names of the objects are composed by the name of the class,
prefixed with "T".

You can see that the object TWindow contains data fields, parameters and methods.
The parameters defined by "param" macro are compile time constants which values
are assigned automatically. These constants are local labels for the object
structure.
They are also inherited from the parent structure.

The methods are very similar to parameters, in that they are constants, defined
in compile time. But besides the value, the method also have list of
arguments, passed to the method, when executed.

In the above example, TButton.width parameter is inherited from TWindow and
have the same value as TWindow.width parameter.

Also, TWindow have all fields of TObject defined as well.

If we have to translate TWindow definition in plain FASM syntax it will looks
similar to this:
;begin
    struc TWindow {
      .ptrClass     dd ?

      .mxAccess     dd ?
      .ptrVar       dd ?

      .OnCreate     dd ?
      .OnDestroy    dd ?

      .handle       dd ?
      .Fcaption     dd ?
      .Fcursor      dd ?

      .AddChild = $80000000
      .x        = $80000001
      .y        = $80000002
      .width    = $80000003
      .height   = $80000004
      .visible  = $80000005
      .caption  = $80000006
      .parent   = $80000007
      .cursor   = $80000008
      .Refresh  = $80000009
    }
    virtual at 0
      TWindow TWindow
      sizeof.TWindow = $
    end virtual
;end

------------------

### "objects.asm" library. 

[#object]

------------------


### "sysevents.asm" library 

[#sysevents.asm]

This library contains event codes and data structures for FreshGUI OS independent
events. For now only several events are defined:
;begin
    ; mouse events
    seMouseMove
    seMouseEnter
    seMouseLeave
    seMouseBtnPress
    seMouseBtnRelease
    seMouseBtnClick
    seMouseBtnDblClick

    ; keyboard events
    seKbdKeyPress
    seKbdKeyRelease
    seKbdStatusChanged
    seKbdChar

    ; Window handling events
    sePaint
    seScroll
    seFocusIn
    seFocusOut
    seMoveResize
;end
These events cover mouse, keyboard and window appearance and behavior events.

Every event have some arguments that have to be sent to the recipient event handler.
The event code and the event arguments are contained in data structure, defined for
every kind of events.

The first dword of the event structure is the field .event that contains the
event code.

Here are the structures defined in sysevents.asm


[#TSysEvent]
;begin
    struct TSysEvent
      .event  dd  ?
    ends
;end
The base event structure. The field `.event` contains the code of the event, as described above.


[#TMouseMoveEvent]
;begin
    struct TMouseMoveEvent
      . TSysEvent
      .x         dd ?
      .y         dd ?
    ends
;end
The event is generated when the mouse cursor moves over some window.
The fields `.x` and `.y` contains the coordinates of the mouse cursor relative to
the upper-left cornet of the window, this message is sent to.


[#TMouseButtonEvent]
;begin
     struct TMouseButtonEvent
      . TSysEvent
      .Button    dd ?
      .kbdStatus dd ?
    ends
;end
This event is generated when some of the mouse buttons changes its state.
The button that changes its state is specified in the field `.Button`.

This field can accept following values:
;begin
    mbLeft      = 0
    mbMiddle    = 1
    mbRight     = 2
;end
The field `.kbdStatus` contains the status of remaining mouse buttons and
keyboard modifying buttons. These buttons are represented by bits in the field:
;begin
    maskBtnLeft     = $0100
    maskBtnMiddle   = $0200
    maskBtnRight    = $0400
    maskCtrl        = $0800
    maskShift       = $1
    maskCapsLock    = $2
    maskCtrl        = $4
    maskAlt         = $8
    maskScrLk       = $10
;end

[#TMouseEnterEvent]
;begin
    struct TMouseEnterEvent
      . TSysEvent
    ends
;end
This event is generated when the mouse cursor enters or leaves some control.
There is no additional parameters besides the event code.


[#TKeyboardEvent]
;begin
    struct TKeyboardEvent
      . TSysEvent
      .key       dd  ?
      .kbdStatus dd  ?
    ends
;end

This event is generated on keyboard button press/release. The field `.key` contains
the code of the pressed button. `.kbdStatus` have the same meaning and the same
values as in TMouseButtonEvent.


[#TPaintEvent]
;begin
    struct TPaintEvent
      . TSysEvent
      .context dd ?
      .rect    RECT
    ends
;end
TPaintEvent is generated when given control have to be repainted. The field `.context`
contains a pointer to [#TContext] structure where the program have to draw.

The field `.rect` is the rectangle of the control that needs to be repainted.


[#TScrollEvent]
;begin
    struct TScrollEvent
      . TSysEvent
      .ScrollBar  dd ?      ; 0
      .ScrollCmd  dd ?      ;
      .Value      dd ?      ; Distance for scUp and scDown and position for scTrack
    ends
;end
This event is sent to the window when it needs to be scrolled.
The field `.ScrollBar` have value 0 for the horizontal scrolling and 1 for vertival.
There are defined constants for these values:
;begin
    scrollX = 0
    scrollY = 1
;end
The field `.ScrollCmd` can have following values:
;begin
    scTrack   = 1
    scUp      = 2
    scDown    = 3
    scWheelUp = 4
    scWheelDn = 5
;end
The field `.Value` contains the absolute position where to scroll the window, for the
command scTrack, and relative distance of the scroll for all remaining commands.


[#TCloseEvent]
;begin
    struct TCloseEvent
      . TSysEvent
      .reason dd ?          ; how the close was requested?
    ends
;end

This event is sent to the window, when the window have to be closed.
`.reason` field defines the reason for the operation. It can have following values:
;begin
    cerFromUser = 0  ;The user pressed X button on the window header, pressed alt+F4
                     from the keyboard, or choose "Close" from the title menu.

    cerFromProgram = 1 ; Method Close was executed from the program.
;end

[#TFocusEvent]
;begin
    struct TFocusInEvent
      . TSysEvent
    ends
;end
This event is sent when the window receives or lose the focus.


[#TMoveResizeEvent]
;begin
    struct TMoveResizeEvent
      . TSysEvent
      .newX  dd ?
      .newY  dd ?
      .newWidth  dd ?
      .newHeight dd ?
    ends
;end
This event is generated when the user resizes the window or moves it to another place.
The fields specify the new coordinates and sizes.


-------------------

### "main.asm" library. 

[#main.asm]

This library implements the procedures for the main program loop of the GUI application.
The modal dialogs procedure is also here.


[#Run]
;begin
    proc Run
;end
This procedure is the main program loop of the GUI application.
The procedure Run process all pending system events, then calls once the OnIdle
event handler of the [#TApplication] object and then sleeps until new events are
sent by the OS.

When the OS terminates the application — the procedure returns an exit code.

The programmer uses this procedure following way:
;begin
        stdcall Run
        push    eax             ; eax contains the exit code.

        FinalizeAll             ; free all resources.

        stdcall Terminate       ; the exit code is already in the stack.
;end

[#ShowModal]
;begin
    proc ShowModal, .pForm, .pParent
;end
Shows the form `[.pForm]` as a modal dialog window with parent window `[.pParent]` —
i.e. the parent window is disabled until the modal windows is visible.

The procedure returns the modal result in EAX. The modal result is also stored in
`TForm.ModalResult` field of the modal form.


[#ProcessSystemEvents]
;begin
    proc ProcessSystemEvents
;end
This procedure process the events generated by the OS. If there are waiting
events in the queue, the procedure reads them, translates them to FreshGUI
event data structures and calls the event handlers of the respective windows.

If there is no pending events in the queue, ProcessSystemEvents ends with CF=0

The second task this procedure serves is to detect the end of the application.
In this case it ends with CF=1.

This procedure is call from the main event loop of the application. ([#Run] procedure).
Also, the user can periodically call this procedure in order to not allow
hanging of the user interface during long processing of some data.


[#WaitForSystemEvent]
;begin
    proc WaitForSystemEvent
;end
This procedure waits until some system message is posted to the application
event queue. Then it exits. During the wait, very low CPU power is consumed
by the application.


-------------------


### "ObjTemplates.asm" library 

[#templates]

This library contains the template engine of FreshGUI.
The template engine provides creation of complex window structures with tree
layout from memory data structure, called template. The templates makes
creation of dialog windows containing children windows and non visual objects.

Templates can be visually created and edited. The template format used by
FreshLib is flexible and allows all parameters and fields of the objects to
be set to needed values during creation of the window.


The template is consisted from one or more data structures of type TObjTemplate,
defined following way:
;begin
    struct TObjTemplate
      .flags     dd  ?
      .class     dd  ?
      .ptrVar    dd  ?
      .paramsize dd  ?
      .params:
    ends
;end
`.flags` — controls what is the place of the object in the whole tree structure.
Can accept one or more of the following values, combined with OR:

`tfChild`  — means the object is a child of the last object with tfParent set.

`tfParent` — means the given object is parent and there will be at least one next
TObjTemplate structure that will be a child object.

`tfEnd` — means the given object is the last child of its parent.
Note, that one object can be parent and child in the same time.
If the current template element is at the root level — the processing of
template stops, after creating the current element and all its children.

.class - pointer to TObjectClass data structure for the created object.

.ptrVar - pointer to dword variable that to accept the pointer to the created object.

.paramsize — the size of the additional data to the end of the template.
Note, that TObjTemplate is variable length structure, not fixed. sizeof.TObjTemplate
contains the size of the header part of the structure.

.params — after the header fields there can be arbitrary count of dword pairs:
(paramID, Value) that to be set to the object during creation. This sequence
ends with dword $FFFFFF (-1) value for paramID.

Easy creation of templates is provided with macro ObjTemplate:

[#ObjTemplate]
;begin
    macro ObjTemplate  flags, class, name, [id, param]
;end
This macro allows use of string values for params and computes automatically
the values for TObjTemplate.paramsize;
The macro have following arguments:

* flags — set of (tfChild, tfParent, tfEnd) constants.

* class — the base name of the object class (without prefix C) — i.e. Form,
        Window, Button, etc.

* name — label of the variable to receive the pointer to the created object.

* id — parameter ID or offset in the object structure.

* param — value of the parameter. Can be dword number or string constant. In the
case the parameter value is string, it will be automatically created in
the memory and the pointer to this string will be placed as a param value.

One example of template structure:
;begin
    ObjTemplate  tfParent or tfEnd, Form, frmMain,      \
                             visible, TRUE,             \
                             x, 100,                    \
                             y, 50,                     \
                             width, 640,                \
                             height, 480,               \
                             caption, 'Fresh portable Win32/Linux application test.'

      ObjTemplate  tfChild, Button, btnChild1,          \
                             visible, TRUE,             \
                             x, 64,                     \
                             y, 48,                     \
                             width, 64,                 \
                             height, 24,                \
                             caption, 'Button1',        \
                             OnClick, Button1Click

      ObjTemplate  tfChild or tfEnd, Button, btnChild2, \
                             x, 136,                    \
                             y, 48,                     \
                             width, 64,                 \
                             height, 24,                \
                             caption, 'Button2' ,       \
                             visible, TRUE
;end

The template engine provides one single procedure:

[#CreateFromTemplate]
;begin
    proc CreateFromTemplate, .ptrTemplate, .parent
;end
This procedure creates all objects from the template, pointed by `[.ptrTemplate]`
as a parent of `[.parent]` argument.

`.ptrTemplate` points to TObjTemplate structure.

`.parent` points to TObject descendant structure. In most cases it will be
actually descendant of TWindow or NULL if the created object is not a child
of any window.

Returns: *EBX* contains a pointer to the topmost of the created object
(it is first of the created objects)

All pointers of the objects are stored in the specified in the template
variables ( i.e. `[TObjTemplate.ptrVar]`)


------------------

### "TObject.asm" library 

[#TObject]

This library implements TObject object class. This is the root class for all object clases in
FreshLib. It is defined following way:
;begin
    object TObject
      .ptrClass     dd ?

      .mxAccess     dd ?
      .ptrVar       dd ?

      .OnCreate     dd ?
      .OnDestroy    dd ?

      method .AddChild, .objchild
    endobj
;end

------------------

### "TApplication.asm" library 

[#TApplication]
;begin
    object TApplication, TObject
      .MainWindow   dd ?
      .Accelerators dd ?
      .OnIdle       dd ?
    endobj
;end
This object class represents the whole GUI application and handles some properties that are
application-wide. For example it keeps the main windows of the application, the list of
keyboard accelerators, etc.
Only one instance of this object must be created during the initialization of the application,
before the call of [#Run] procedure.

`.MainWindow` field is a pointer to the main window of the application. When this window is
closed, the whole application terminates as well.

`.Accelerators` fields is a pointer to a list with application-wide keyboard accelerators.

`.OnIdle` is an application callback that will be call once everytime the events queue is empty.
The user can process here some tasks that have to be processed with low priority. The usual
use of this callback is to detect what toolbar buttons and menu items have to be enabled or
disabled, depending to the current state of the program.


------------------

### "TWindows.asm" library 

[#TWindow]
;begin
    object TWindow, TObject

      .handle       dd ?

      ._x           dd ?
      ._y           dd ?
      ._width       dd ?
      ._height      dd ?

      ._visible     dd ?

      ._bounds_changed dd ?

      ._border      dd ?

      ._align       dd ?

      ._FreeArea    TBounds

      ._caption     dd ?
      ._cursor      dd ?

      .OnKeyPress   dd ?

    ; parameters

      param .x
      param .y
      param .width
      param .height

      param .Align

      param .FreeArea

      param .borderKind
      param .Zorder

      param .Visible
      param .Caption
      param .Parent
      param .Cursor
      param .Children

      method .Refresh
      method .Focus
      method .AlignChildren
      method .ToBack
      method .ToFront

      method ._ComputeFreeArea
    endobj
;end

------------------


### "TScrollWindow.asm" library 

[#TScrollWindow]

;begin
    object TScrollWindow, TWindow
      ._HScroller TScrollbar
      ._VScroller TScrollbar

      method HScrollSet, .Pos, .Max, .Page
      method VScrollSet, .Pos, .Max, .Page
    endobj
;end


------------------

### "TForm.asm" library 

[#TForm]
;begin
    object TForm, TWindow

      .ModalResult  dd ?

      .OnClose dd ?

      param .type
    endobj
;end

------------------

### "TButton.asm" library 

[#TButton]
;begin
    object TButton, TWindow
      .state      dd ?
      .Ficon      dd ?
      .FiconAlign dd ?
      .Ftextalign dd ?

      .ModalResult dd ?
      .OnClick dd ?

      param .TextAlign
      param .Icon
      param .IconPosition
    endobj
;end


------------------

### "TLabel.asm" library 

[#TLabel]
;begin
    object TLabel, TWindow
      .Ftextalign dd ?

      param .TextAlign        ; text align flags.
      param .Control          ; control that to be activated
    endobj
;end

------------------

### "TImagelabel.asm" library 

[#TImageLabel]
;begin
    object TImageLabel, TWindow
      .FImageAlign dd ?
      .FImage      dd ?
      .FMask       dd ?
      .FBackground dd ?

      param .ImageAlign
      param .Image
      param .Mask
    endobj
;end


------------------

### "TEdit.asm" library 

[#TEdit]
;begin
    object TEdit, TWindow
      ._Text  dd ?
      ._Len   dd ?  ; the length of the string in characters. (UTF-8)
      ._Start dd ?  ; Where the string begins to be displayed in the edit window.
      ._Pos   dd ?  ; Position of the caret in the string.
      ._Sel   dd ?  ; Position of the selction in the string.

      ._MarginLeft dd ?
      ._MarginRight dd ?

      ._Focused dd ? ; flag

      param .Text
    endobj
;end


------------------

### "TProgressbar.asm" library 

[#TProgress]
;begin
    object TProgress, TWindow
      ._Pos   dd ?
      ._Max   dd ?
      ._Color dd ?

      param .Pos
      param .Max
      param .Color

      method .Step
    endobj
;end

------------------

### "TTreeView.asm" library 

[#TTreeView]
;begin
    object TTreeView, TScrollWindow
      ._items dd ?
      ._first dd ?
      ._pShadow dd ?

      .OnItemDelete  dd ?

      param .Focused

      method .AddItem, .iParent
      method .DelItem, .iItem
      method .GetItem, .index
    endobj
;end

------------------

## FreshLib directory "FreshEdit/" 

This directory contains one additional control class — TFreshEdit.
It is complex and powerful text editor control, intended to be used
in the advanced programmer's text editors - such as Fresh IDE.

------------------

### "TFreshEdit.asm" library 


[#TFreshEdit]

;begin
    object TFreshEdit, TScrollWindow
      ._Font            dd  ?   ; font of the editor.

    ; main editor font sizes
      ._fontheight      dd  ?   ; in pixels.
      ._fontwidth       dd  ?   ; in pixels.
      ._fontdescent     dd  ?   ; in pixels.

    ; system font sizes (used for additional texts and line numbers)
      ._fontheight2     dd  ?   ; in pixels.
      ._fontwidth2      dd  ?   ; in pixels.
      ._fontdescent2    dd  ?   ; in pixels.

      .__LeftMargin     dd  ?   ; width of the left margin field. Auto computed.
      .__NumberMargin   dd  ?   ; width of the field for the line number. Auto computed.

      ._cols            dd  ?   ; width of the window in text columns.
      ._rows            dd  ?   ; height of the window in text rows.
                                ; must to be update on resize and on font change.

      ._pLines          dd  ?   ; pointer to TArray of TEditorLine items.
      ._pLengths        dd  ?   ; pointer to TArray with counts of the lines with given length.

      ._pUndoList       dd  ?   ; pointer to TArray of TUndoInfo
      ._pRedoList       dd  ?   ; pointer to TArray of TUndoInfo

      ._pShadow         dd  ?   ; pointer to TBackBuffer object.
      ._fShadowValid    dd  ?   ;

    ; view change fields

      ._TopLine         dd  ?   ; number of the line that is at the topmost line of the window.
      ._TopOffset       dd  ?   ; how many rows the top line is off the screen (for word wrapped lines)
      ._LeftColumn      dd  ?   ; the column of the text at the leftmost side of the window.

      ._CaretChar       dd  ?   ; the number of the char the caret resides.
      ._CaretLine       dd  ?   ; the index of the line the caret resides.

      ._SelChar         dd  ?
      ._SelLine         dd  ?

      ._fReadOnly       dd  ?
      ._SelMode         dd  ?        ; NOTE: on selmBlock, the word wrap should be OFF
      ._InsMode         dd  ?
      ._TabStop         dd  ?

    ; end change fields

      ._prevTopLine     dd  ?
      ._prevTopOffset   dd  ?
      ._prevLeftColumn  dd  ?

      ._prevCaretChar   dd  ?
      ._prevCaretLine   dd  ?

      ._prevxDelta      dd  ?
      ._prevyDelta      dd  ?

      ._prevSelMode     dd  ?
      ._prevInsMode     dd  ?

    ; end backup fields

      ._DragButton      dd  ?

      ._procSyntax      dd  ?   ; syntax highlighter procedure.

    ; icons and masks for the left margin
      ._iconBreakpointA dd  ?       ; active breakpoint icon.
      ._iconBreakpointI dd  ?       ; inactive breakpoint icon.
      ._iconDebugInfo   dd  ?
      ._maskBreakpointA dd  ?
      ._maskBreakpointI dd  ?
      ._maskDebugInfo   dd  ?
      ._iconUnfold      dd  ?
      ._iconFold        dd  ?
      ._maskUnfold      dd  ?

    ; Event handlers

      .OnControlKey     dd  ?

    ; Parameters
      param .Selection      ; selected text read/write

      param .CurrentLine    ; TEditorLine where caret resides. read only
      param .Text           ; whole text; read/write
      param .MaxLineLen

    ; Methods

      method .Clear          ; clears the text in the editor.

    ; navigation methods

      method .Move, .direction, .count, .force      ; moves the caret

      method .LineBegin
      method .LineEnd
      method .ScreenBegin
      method .ScreenEnd
      method .FileBegin
      method .FileEnd

    ; editing methods

      method .DeleteSel
      method .InsertLine, .index    ; index = -1 inserts at current position of the caret.
                                    ; index = -2 appends the line at the end of the text.
      method .DeleteLine, .index    ; index = -1 deletes the line on the current position of the caret.

    ; block processing methods.
      method .DeleteText, .lineFrom, .charFrom, .lineTo, .charTo, .BlockKind
      method .GetText, .lineFrom, .charFrom, .lineTo, .charTo, .BlockKind

    ; Undo/Redo functions.

      method .RegisterForUndo, .operation, .data

      method .Undo
      method .Redo

      method .ClearUndo

    ; these two methods are flexible, but very slow.
    ; .Text parameter seting is fastest way to change whole text of the editor.

      method .InsertChar, .char
      method .InsertString, .hstring    ; inserts a string at the caret position.
                                        ; If the string contains formating chars they are
                                        ; processed properly.
      method .DelChar      ; deletes the char under the caret.

    ; format and appearance methods
      method .FormatLine, .index

    ; themes methods

      method LoadTheme, .configdb, .directory

    endobj
;end

------------------

### "fasm_syntax.asm" library 


[#SyntaxFASM]
;begin
    proc SyntaxFASM, .hString, .pAttr, .SynContext
;end


------------------

\documentclass[a4paper,12pt]{book}

\usepackage[pdftex,bookmarks=true,hidelinks,pdfstartview=FitH]{hyperref}

\usepackage{longtable}

\usepackage{anysize}
\makeindex

\begin{document}
\author{Tomasz Grysztar}
\title{flat assembler 1.70\\\small{Programmer's Manual}}
\date{}
\maketitle


\chapter{Introduction}
This chapter contains all the most important information you need to begin
using the flat assembler. If you are experienced assembly language programmer,
you should read at least this chapter before using this compiler.

\section{Compiler overview}
Flat assembler is a fast assembly language compiler for the x86
architecture processors, which does multiple passes to optimize
the size of generated machine code. It is self--compilable and
versions for different operating systems are provided. They are
designed to be used from the system command line and they should
not differ in behavior.

This document describes also the IDE version designed for the
Windows system, which uses the graphical interface instead of
console and has the integrated editor. But from the compilation point of view
it has exactly the same functionality as all the
console versions, and so later parts (beginning from
\ref{sec:syntax}) of this document are common with other releases.
The executable of the IDE version is called \verb"fasmw.exe",
while \verb"fasm.exe" is the command line version.

\subsection{System requirements}
All versions require the x86 architecture 32--bit processor (at
least 80386), although they can produce programs for the x86
architecture 16--bit processors, too. Windows console version
requires any Win32 operating system, while Windows GUI version
requires the Win32 GUI system version 4.0 or higher, so it should
run on all systems compatible with Windows 95.

The example source provided with this version require you have
environment variable \verb"INCLUDE" set to the path of the
\verb"include" directory, which is the part of flat assembler
package. If such variable already exists in your system and
contains paths used by some other program, it's enough to add the
new path to it (the different paths should be separated with
semicolons). If you don't want to define such variable in the
system, or don't know how to do it, you can set it for the flat
assembler IDE only by editing the \verb"fasmw.ini" file in its
directory (this file is created by \verb"fasmw.exe" when it's
executed, but you can also create it by yourself). In this case
you should add the \verb"Include" value into the
\verb"Environment" section. For example, when you have unpacked
the flat assembler files into the \verb"c:\fasmw" directory, you
should put the following two lines into your
\verb"c:\fasmw\fasmw.ini" file:
\begin{verbatim}
[Environment]
Include = c:\fasmw\include
\end{verbatim}
If you don't define the \verb"INCLUDE" environment variable
properly, you will have to manually provide the full path to the
Win32 includes in every program you want to compile.

\subsection{Compiler usage}
To start working with flat assembler, simply double click on the icon of \verb"fasmw.exe" file,
or drag the icon of your source file onto it. You can also later open new source files with
the \emph{Open} command from the \emph{File} menu, or by dragging the files into the editor window.
You can have multiple source files opened at one time, each one is represented by one tab button
at the bottom of the editor window. To select file for editing, click on the corresponding tab
with left mouse button. Compiler by default operates on the file you are currently editing, but you
can force it to always operate on some particular file by clicking the appropriate tab with right mouse
button and selecting the \emph{Assign} command. Only single file can be assigned to compiler at one time.

When your source file is ready, you can execute the compiler with \emph{Compile} command from the
\emph{Run} menu. When the compilation is successful, compiler will display the summary of compilation
process; otherwise it will display the information about error that occurred. Compilation summary
includes the information of how many passes was done, how much time it took, and how many bytes were
written into destination file. It also contains a text field called \emph{Display}, in which will
appear any messages from the \verb"display" directives in source (see \ref{sec:other}). Error
summary consists at least of the error message and a text field \emph{Display}, which has the same
purpose as above. If error is related to some specific line of source code, the summary contains also
a text field \emph{Instruction}, which contains the preprocessed form of instruction that caused an
error if the error occured after the preprocessor stage (otherwise it's empty) and the \emph{Source}
list, which shows location of all the source lines related to this error, when you select a line from
this list, it will be at the same time selected in the editor window (if file which contains that line
is not loaded, it will be automatically added).

The \emph{Run} command also executes the compiler, and in case of successful compilation it runs the
compiled program if only it is one of the formats that can be run in Windows environment, otherwise
you'll get a message that such type of file cannot be executed. If an error occurs, compiler displays
information about it in the same form as if the \emph{Compile} command was used.

If the compiler runs out of memory, you can increase the memory allocation in the \emph{Compiler setup}
dialog, which you can start from the \emph{Options} menu. You can specify there the amount of kilobytes
that the compiler should use, and also the priority of the compiler's thread.

If you want only one instance of program to be running, add
the \verb"OneInstanceOnly=1" setting to the \verb"Options" section
of the \verb"fasmw.ini" file.

\subsection{Keyboard commands in editor}
This section lists the all keyboard commands available when working with
editor. Except for the keys listed as specific ones, they are common with the
DOS IDE for flat assembler.

\subsubsection{Movement:}
\begin{longtable}[l]{p{4cm}l}
    Left arrow       & move one character left \\
    Right arrow      & move one character right \\
    Up arrow         & move one line up \\
    Down arrow       & move one line down \\
    Ctrl+Left arrow  & move one word left \\
    Ctrl+Right arrow & move one word right \\
    Home             & move to the beginning of line \\
    End              & move to the end of line \\
    PageUp           & move one page up \\
    PageDown         & move one page down \\
    Ctrl+Home        & move to the first line of page \\
    Ctrl+End         & move to the last line of page \\
    Ctrl+PageUp      & move to the first line of text \\
    Ctrl+PageDown    & move to the last line of text \\
\\
\multicolumn{2}{l}{Each of the movement keys pressed with Shift selects text.}
\end{longtable}

\subsubsection{Editing:}
\begin{longtable}[l]{p{4cm}l}
    Insert         &  switch insert/overwrite mode \\
    Alt+Insert     &  switch horizontal/vertical blocks \\
    Delete         &  delete current character \\
    Backspace      &  delete previous character \\
    Ctrl+Backspace &  delete previous word \\
    Alt+Backspace  &  undo previous operation (also Ctrl+Z) \\
    Ctrl+Y         &  delete current line \\
    F6             &  duplicate current line \\
\end{longtable}

\subsubsection{Block operations:}
\begin{longtable}[l]{p{4cm}l}
    Ctrl+Insert  & copy block into clipboard (also Ctrl+C) \\
    Shift+Insert & paste block from the clipboard (also Ctrl+V) \\
    Ctrl+Delete  & delete block \\
    Shift+Delete & cut block into clipboard (also Ctrl+X) \\
    Ctrl+A       & select all text \\
\end{longtable}

\subsubsection{Search:}
\begin{longtable}[l]{p{4cm}l}
    F5       & go to specified position (also Ctrl+G) \\
    F7       & find (also Ctrl+F) \\
    Shift+F7 & find next (also F3) \\
    Ctrl+F7  & replace (also Ctrl+H) \\
\end{longtable}

\subsubsection{Compile:}
\begin{longtable}[l]{p{4cm}l}
    F9       & compile and run \\
    Ctrl+F9  & compile only \\
    Shift+F9 & assign current file as main file to compile \\
    Ctrl+F8  & compile and build symbols information \\
\end{longtable}

\subsubsection{Other keys:}
\begin{longtable}[l]{p{4cm}l}
    F2              & save current file \\
    Shift+F2        & save file under a new name \\
    F4              & load file \\
    Ctrl+N          & create new file \\
    Ctrl+Tab        & switch to next file \\
    Ctrl+Shift+Tab  & switch to previous file \\
    Alt+[1-9]       & switch to file of given number \\
    Esc             & close current file \\
    Alt+X           & close all files and exit \\
    Ctrl+F6         & calculator \\
    Alt+Left arrow  & scroll left \\
    Alt+Right arrow & scroll right \\
    Alt+Up arrow    & scroll up \\
    Alt+Down arrow  & scroll down \\
    Alt+Delete      & discard undo information \\
\end{longtable}

\subsubsection{Specific keys:}
\begin{longtable}[l]{p{4cm}l}
    F1     & search for keyword in selected help file \\
    Alt+F1 & contents of selected help file \\
\end{longtable}

\subsection{Editor options}
In the \emph{Options} menu resides also a list of editor options, which may be turned on or off and
affect the behavior of editor. This section describes these options.

\emph{Secure selection} -- when you turn this option on, the selected block never
gets deleted when you start typing. When you do any text--changing operation,
the selection is cancelled, not affecting in any way the text that was
selected, and then the command is performed. When this option is off and you
start typing, the current selection is discarded, also Del key simply deletes
the selected block (when secure selection is on you have to use Ctrl+Del).

\emph{Automatic brackets} -- when you type any of the opening brackets, the closing
one is automatically put just after caret.

\emph{Automatic indents} -- when you press Enter to start a new line, the caret is
moved into the new line at the same position, where in the previous line the
first non-blank character is placed. If you are breaking the line, and there
were some non-blank characters after the caret when you pressed Enter, they
are moved into the new line at the position of indent, any blank characters
that were between the caret and them are ignored.

\emph{Smart tabulation} -- when you press Tab, it moves you to the position just
below the next sequence of non-blank characters in the line above starting
from the position just above where you were. If no such sequence is found in
line above, the standard tabulation size of 8 characters is used.

\emph{Optimal fill on saving} -- with this option enabled, when the file is saved,
all blank areas are filled with the optimal combination of tabs and spaces to
get the smaller file size. If this option is off, the blank areas are saved as
filled with spaces (but the spaces at the ends of lines are not saved).

\emph{Revive dead keys} -- when this option is turned on, it disables inside the
editor the so--called
dead keys (keys that don't immediately generate the character, but wait for a next key
to decide what character to put -- usually you enter the character of a dead key by
pressing a space key after it). It may be useful if key for entering some of the characters that
you need to enter often into assembly source is a dead key and you don't need this
functionality for writing programs.

\subsection{Executing compiler from command line}
To perform compilation from the command line you need to execute
the \verb"fasm.exe" executable, providing two parameters -- first
should be name of source file, second should be name of
destination file. If no second parameter is given, the name for
output file will be guessed automatically. After displaying short
information about the program name and version, compiler will read
the data from source file and compile it. When the compilation is
successful, compiler will write the generated code to the
destination file and display the summary of compilation process;
otherwise it will display the information about error that
occurred.

The source file should be a text file, and can be created in any
text editor. Line breaks are accepted in both DOS and Unix
standards, tabulators are treated as spaces.

In the command line you can also include \verb"-m" option followed
by a number, which specifies how many kilobytes of memory flat
assembler should maximally use. In case of DOS version this
options limits only the usage of extended memory. The \verb"-p"
option followed by a number can be used to specify the limit for
number of passes the assembler performs. If code cannot be
generated within specified amount of passes, the assembly will be
terminated with an error message. The maximum value of this
setting is 65536, while the default limit, used when no such
option is included in command line, is 100. It is also possible to
limit the number of passes the assembler performs, with the
\verb"-p" option followed by a number specifying the maximum
number of passes.

There are no command line options that would affect the output of
compiler, flat assembler requires only the source code to include
the information it really needs. For example, to specify output
format you specify it by using the \verb"format" directive at the
beginning of source.

\subsection{Command line compiler messages}
As it is stated above, after the successful compilation, the
compiler displays the compilation summary. It includes the
information of how many passes was done, how much time it took,
and how many bytes were written into the destination file. The
following is an example of the compilation summary:
\begin{verbatim}
flat assembler  version 1.70 (16384 kilobytes memory)
38 passes, 5.3 seconds, 77824 bytes.
\end{verbatim}
In case of error during the compilation process, the program will
display an error message. For example, when compiler can't find
the input file, it will display the following message:
\begin{verbatim}
flat assembler  version 1.70 (16384 kilobytes memory)
error: source file not found.
\end{verbatim}
If the error is connected with a specific part of source code, the
source line that caused the error will be also displayed. Also
placement of this line in the source is given to help you finding
this error, for example:
\begin{verbatim}
flat assembler  version 1.70 (16384 kilobytes memory)
example.asm [3]:
        mob     ax,1
error: illegal instruction.
\end{verbatim}
It means that in the third line of the \verb"example.asm" file
compiler has encountered an unrecognized instruction. When the
line that caused error contains a macroinstruction, also the line
in macroinstruction definition that generated the erroneous
instruction is displayed:
\begin{verbatim}
flat assembler  version 1.70 (16384 kilobytes memory)
example.asm [6]:
        stoschar 7
example.asm [3] stoschar [1]:
        mob     al,char
error: illegal instruction.
\end{verbatim}
It means that the macroinstruction in the sixth line of the
\verb"example.asm" file generated an unrecognized instruction with
the first line of its definition.

\subsection{Output formats}
By default, when there is no \verb"format" directive in source file, flat
assembler simply puts generated instruction codes into output, creating this
way flat binary file. By default it generates 16--bit code, but you can
always turn it into the 16--bit or 32--bit mode by using \verb"use16" or
\verb"use32" directive. Some of the output formats switch into 32--bit mode,
when selected -- more information about formats which you can choose can be
found in \ref{sec:formatter}.

The extension of destination file is chosen automatically by compiler, depending
on the selected output format.

All output code is always in the order in which it was entered into the
source file.

\section{Assembly syntax}
\label{sec:syntax}
The information provided below is intended mainly for the assembler
programmers that have been using some other assembly compilers before.
If you are beginner, you should look for the assembly programming tutorials.

Flat assembler by default uses the Intel syntax for the assembly
instructions, although you can customize it using the preprocessor
capabilities (macroinstructions and symbolic constants). It also has its own
set of the directives -- the instructions for compiler.

All symbols defined inside the sources are case--sensitive.

\begin{table}[h]
\begin{center}\begin{tabular}{|c|c|c|}
\hline
Operator & Bits & Bytes \\
\hline \hline
\verb"byte" & 8 & 1 \\
\verb"word" & 16 & 2 \\
\verb"dword" & 32 & 4 \\
\verb"fword" & 48 & 6 \\
\verb"pword" & 48 & 6 \\
\verb"qword" & 64 & 8 \\
\verb"tbyte" & 80 & 10 \\
\verb"tword" & 80 & 10 \\
\verb"dqword" & 128 & 16 \\
\verb"xword" & 128 & 16 \\
\verb"qqword" & 256 & 32 \\
\verb"yword" & 256 & 32 \\
\hline
\end{tabular}\end{center}
\caption{Size operators.}\label{tab:size_operators}
\end{table}

\begin{table}[bt]
\begin{center}\begin{tabular}{|c|c||cccccccc|}
\hline
Type & Bits & & & & & & & & \\
\hline\hline
 & 8 & \verb"al" & \verb"cl" & \verb"dl" & \verb"bl" & \verb"ah" & \verb"ch" & \verb"dh" & \verb"bh" \\
General & 16 & \verb"ax" & \verb"cx" & \verb"dx" & \verb"bx" & \verb"sp" & \verb"bp" & \verb"si" & \verb"di" \\
 & 32 & \verb"eax" & \verb"ecx" & \verb"edx" & \verb"ebx" & \verb"esp" & \verb"ebp" & \verb"esi" & \verb"edi" \\
\hline
Segment & 16 & \verb"es" & \verb"cs" & \verb"ss" & \verb"ds" & \verb"fs" & \verb"gs" & & \\
\hline
Control & 32 & \verb"cr0" & & \verb"cr2" & \verb"cr3" & \verb"cr4" & & & \\
\hline
Debug & 32 & \verb"dr0" & \verb"dr1" & \verb"dr2" & \verb"dr3" & & & \verb"dr6" & \verb"dr7" \\
\hline
FPU & 80 & \verb"st0" & \verb"st1" & \verb"st2" & \verb"st3" & \verb"st4" & \verb"st5" & \verb"st6" & \verb"st7" \\
\hline
MMX & 64 & \verb"mm0" & \verb"mm1" & \verb"mm2" & \verb"mm3" & \verb"mm4" & \verb"mm5" & \verb"mm6" & \verb"mm7" \\
\hline
SSE & 128 & \verb"xmm0" & \verb"xmm1" & \verb"xmm2" & \verb"xmm3" & \verb"xmm4" & \verb"xmm5" & \verb"xmm6" & \verb"xmm7" \\
\hline
AVX & 256 & \verb"ymm0" & \verb"ymm1" & \verb"ymm2" & \verb"ymm3" & \verb"ymm4" & \verb"ymm5" & \verb"ymm6" & \verb"ymm7" \\
\hline
\end{tabular}\end{center}
\caption{Registers.}
\label{tab:registers}
\end{table}

\subsection{Instruction syntax}
Instructions in assembly language are separated by line breaks, and one
instruction is expected to fill the one line of text. If a line contains
a semicolon, except for the semicolons inside the quoted strings, the rest of
this line is the comment and compiler ignores it. If a line ends with \verb"\"
character (eventually the semicolon and comment may follow it), the next line
is attached at this point.

Each line in source is the sequence of items, which may be one of the three
types. One type are the symbol characters, which are the special characters
that are individual items even when are not spaced from the other ones.
Any of the \verb"+-*/=<>()[]{}:,|&~#`" is the symbol character. The sequence of
other characters, separated from other items with either blank spaces or
symbol characters, is a symbol. If the first character of symbol is either a
single or double quote, it integrates any sequence of characters following
it, even the special ones, into a quoted string, which should end with the same
character, with which it began (the single or double quote) -- however if there
are two such characters in a row (without any other character between them),
they are integrated into quoted string as just one of them and the quoted
string continues then. The symbols other than symbol characters and quoted
strings can be used as names, so are also called the name symbols.

Every instruction consists of the mnemonic and the various number of
operands, separated with commas. The operand can be register, immediate
value or a data addressed in memory, it can also be preceded by size operator
to define or override its size (table \ref{tab:size_operators}). Names of
available registers you can find in table \ref{tab:registers}, their sizes
cannot be overridden. Immediate value can be specified by any numerical
expression.

When operand is a data in memory, the address of that data (also any
numerical expression, but it may contain registers) should be enclosed in
square brackets or preceded by \verb"ptr" operator. For example instruction
\verb"mov eax,3" will put the immediate value 3 into the \verb"eax" register,
instruction \verb"mov eax,[7]" will put the 32--bit value from the address 7
into \verb"eax" and the instruction \verb"mov byte [7],3" will put the
immediate value 3 into the byte at address 7, it can also be written as
\verb"mov byte ptr 7,3". To specify which segment register should be used for
addressing, segment register name followed with a colon should be put just
before the address value (inside the square brackets or after the \verb"ptr"
operator).

\subsection{Data definitions}
\index{DB}\index{RB}\index{DW}\index{DU}\index{RW}\index{DP}\index{RP}\index{DF}\index{RF}
\index{DD}\index{RD}\index{DQ}\index{RQ}\index{DT}\index{RT}
To define data or reserve a space for it, use one of the directives listed
in table \ref{tab:data_directives}. The data definition directive should be
followed by one or more of numerical expressions, separated with commas.
These expressions define the values for data cells of size depending on which
directive is used. For example \verb"db 1,2,3" will define the three bytes of
values 1, 2 and 3 respectively.

The \verb"db" and \verb"du" directives also accept the quoted string values
of any length, which will be converted into chain of bytes when \verb"db"
is used and into chain of words with zeroed high byte when \verb"du" is used.
For example \verb"db 'abc'" will define the three bytes of values 61, 62 and
63.

The \verb"dp" directive and its synonym \verb"df" accept the values
consisting of two numerical expressions separated with colon, the first value
will become the high word and the second value will become the low double
word of the far pointer value. Also \verb"dd" accepts such pointers consisting
of two word values separated with colon, and \verb"dt" accepts the word and quad word value separated
with colon, the quad word is stored first. The \verb"dt" directive with single
expression as parameter accepts only floating point values and creates data in
FPU double extended precision format.

Any of the above directive allows the usage of special \verb"dup" operator to
make multiple copies of given values. The count of duplicates should precede
this operator and the value to duplicate should follow -- it can even be the
chain of values separated with commas, but such set of values needs to be
enclosed with parenthesis, like \verb"db 5 dup (1,2)", which defines five copies
of the given two byte sequence.

\index{FILE}
The \verb"file" is a special directive and its syntax is different. This
directive includes a chain of bytes from file and it should be followed by
the quoted file name, then optionally numerical expression specifying offset
in file preceded by the colon, then -- also optionally -- comma and numerical
expression specifying count of bytes to include (if no count is specified,
all data up to the end of file is included). For example \verb"file 'data.bin'" will
include the whole file as binary data and \verb"file 'data.bin':10h,4" will include
only four bytes starting at offset 10h.

\begin{table}[hbt]
\begin{center}\begin{tabular}{|c||c|c|}
\hline
Size & Define & Reserve \\
(bytes) & data & data \\
\hline \hline
1 & \verb"db" & \verb"rb" \\
& \verb"file" & \\
\hline
2 & \verb"dw" & \verb"rw" \\
& \verb"du" & \\
\hline
4 & \verb"dd" & \verb"rd" \\
\hline
6 & \verb"dp" & \verb"rp" \\
& \verb"df" & \verb"rf" \\
\hline
8 & \verb"dq" & \verb"rq" \\
\hline
10 & \verb"dt" & \verb"rt" \\
\hline
\end{tabular}\end{center}
\caption{Data directives.}
\label{tab:data_directives}
\end{table}

The data reservation directive should be followed by only one numerical
expression, and this value defines how many cells of the specified size
should be reserved. All data definition directives also accept the \verb"?"
value, which means that this cell should not be initialized to any value and
the effect is the same as by using the data reservation directive. The
uninitialized data may not be included in the output file, so its values
should be always considered unknown.

\subsection{Constants and labels}
\label{sec:labels}
In the numerical expressions you can also use constants or labels instead of
numbers. To define the constant or label you should use the specific
directives. Each label can be defined only once and it is accessible from the
any place of source (even before it was defined). Constant can be redefined
many times, but in this case it is accessible only after it was defined, and
is always equal to the value from last definition before the place where it's
used. When a constant is defined only once in source, it is -- like the label --
accessible from anywhere.

\index{=}
The definition of constant consists of name of the constant followed by the
\verb"=" character and numerical expression, which after calculation will
become the value of constant. This value is always calculated at the time the
constant is defined. For example you can define \verb"count" constant by
using the directive \verb"count = 17", and then use it in the assembly
instructions, like \verb"mov cx,count" -- which will become \verb"mov cx,17"
during the compilation process.

There are different ways to define labels. The simplest is to follow the name
of label by the colon, this directive can even be followed by the other
instruction in the same line. It defines the label whose value is equal to
offset of the point where it's defined. This method is usually used to label
the places in code. The other way is to follow the name of label (without a
colon) by some data directive. It defines the label with value equal to
offset of the beginning of defined data, and remembered as a label for data
with cell size as specified for that data directive in table
\ref{tab:data_directives}.

The label can be treated as constant of value equal to offset of labeled
code or data. For example when you define data using the labeled directive
\verb"char db 224", to put the offset of this data into
\verb"bx" register you should use \verb"mov bx,char" instruction, and to put
the value of byte addressed by \verb"char" label to \verb"dl" register,
you should use \verb"mov dl,[char]" (or \verb"mov dl,ptr char"). But when you
try to assemble \verb"mov ax,[char]", it will cause an error, because fasm
compares the sizes of operands, which should be equal. You can force
assembling that instruction by using size override:
\verb"mov ax,word [char]", but remember that this instruction will read the
two bytes beginning at \verb"char" address, while it was defined as a one
byte.

\index{LABEL}
The last and the most flexible way to define labels is to use \verb"label"
directive. This directive should be followed by the name of label, then
optionally size operator and then -- also optionally \verb"at" operator and
the numerical expression defining the address at which this label should be
defined. For example \verb"label wchar word at char" will define a new label
for the 16--bit data at the address of \verb"char". Now the instruction
\verb"mov ax,[wchar]" will be after compilation the same as
\verb"mov ax,word [char]". If no address is specified, \verb"label" directive
defines the label at current offset. Thus \verb"mov [wchar],57568" will copy
two bytes while \verb"mov [char],224" will copy one byte to the same address.

The label whose name begins with dot is treated as local label, and its name
is attached to the name of last global label (with name beginning with
anything but dot) to make the full name of this label. So you can use the
short name (beginning with dot) of this label anywhere before the next global
label is defined, and in the other places you have to use the full name.
Label beginning with two dots are the exception -- they are like global, but
they don't become the new prefix for local labels.

The \verb"@@" name means anonymous label, you can have defined many of them
in the source. Symbol \verb"@b" (or equivalent \verb"@r") references the
nearest preceding anonymous label, symbol \verb"@f" references the nearest
following anonymous label. These special symbol are case--insensitive.

\subsection{Numerical expressions}
In the above examples all the numerical expressions were the simple numbers,
constants or labels. But they can be more complex, by using the arithmetical
or logical operators for calculations at compile time. All these operators
with their priority values are listed in table \ref{tab:operators_priority}.
The operations with higher priority value will be calculated first, you can
of course change this behavior by putting some parts of expression into
parenthesis. The \verb"+", \verb"-", \verb"*" and \verb"/" are standard
arithmetical operations, \verb"mod" calculates the remainder from division.
The \verb"and", \verb"or", \verb"xor", \verb"shl", \verb"shr" and \verb"not"
perform the same logical operations as assembly instructions of those names.
The \verb"rva" and \verb"plt" are special unary operators that perform
conversions between different kinds of addresses, they can be used only with
few of the output formats and their meaning may vary (see \ref{sec:formatter}).

The arithmetical and logical calculations are usually processed as if they
operated on infinite precision 2-adic numbers, and assembler signalizes an
overflow error if because of its limitations it is not table to perform the
required calculation, or if the result is too large number to fit in either
signed or unsigned range for the destination unit size. However \verb"not", \verb"xor"
and \verb"shr" operators are exceptions from this rule -- if the value specified
by numerical expression has to fit in a unit of specified size, and the
arguments for operation fit into that size, the operation will be performed
with precision limited to that size.

\begin{table}[hbt]
\begin{center}\begin{tabular}{|c|c|}
\hline
Priority & Operators \\
\hline \hline
0 & \verb"+" \\
  & \verb"-" \\
\hline
1 & \verb"*" \\
  & \verb"/" \\
\hline
2 & \verb"mod" \\
\hline
3 & \verb"and" \\
  & \verb"or" \\
  & \verb"xor" \\
\hline
4 & \verb"shl" \\
  & \verb"shr" \\
\hline
5 & \verb"not" \\
\hline
6 & \verb"rva" \\
  & \verb"plt" \\
\hline
\end{tabular}\end{center}
\caption{Arithmetical and logical operators by priority.}
\label{tab:operators_priority}
\end{table}

The numbers in the expression are by default treated as a decimal, binary
numbers should have the \verb"b" letter attached at the end, octal number
should end with \verb"o" letter, hexadecimal numbers should begin with \verb"0x" characters
(like in C language) or with the \verb"$" character (like in Pascal language)
or they should end with \verb"h" letter. Also quoted string, when encountered
in expression, will be converted into number -- the first character will become
the least significant byte of number.

The numerical expression used as an address value can also contain
any of general registers used for addressing, they can be added
and multiplied by appropriate values, as it is allowed for x86
architecture instructions.

There are also some special symbols that can be used inside the numerical
expression. First is \verb"$", which is always equal to the value of current
offset, while \verb"$$" is equal to base address of current addressing space.
The other one is \verb"%", which is the number of current repeat in parts of
code that are repeated using some special directives (see \ref{sec:control}).
There's also \verb"%t" symbol, which is always equal to the current time stamp.

Any numerical expression can also consist of single floating point value
(flat assembler does not allow any floating point operations at compilation
time) in the scientific notation, they can end with the \verb"f" letter
to be recognized, otherwise they should contain at least one of the \verb"."
or \verb"E" characters. So \verb"1.0", \verb"1E0" and \verb"1f" define the
same floating point value, while simple \verb"1" defines an integer value.

\subsection{Jumps and calls}
\label{sec:jumps}
The operand of any jump or call instruction can be preceded not only by the
size operator, but also by one of the operators specifying type of the jump:
\verb"short", \verb"near" of \verb"far". For example, when assembler is in 16--bit mode,
instruction \verb"jmp dword [0]" will become the far jump and when assembler is
in 32--bit mode, it will become the near jump. To force this instruction to be
treated differently, use the \verb"jmp near dword [0]" or \verb"jmp far dword [0]" form.

When operand of near jump is the immediate value, assembler will generate
the shortest variant of this jump instruction if possible (but will not create
32--bit instruction in 16--bit mode nor 16--bit instruction in 32--bit mode,
unless there is a size operator stating it). By specifying the jump type
you can force it to always generate long variant (for example \verb"jmp near 0")
or to always generate short variant and terminate with an error when it's
impossible (for example \verb"jmp short 0").


\subsection{Size settings}
When instruction uses some memory addressing, by default the smallest form of
instruction is generated by using the short displacement if only address
value fits in the range. This can be overridden using the \verb"word" or \verb"dword"
operator before the address inside the square brackets (or after the \verb"ptr"
operator), which forces the long displacement of appropriate size to be made.
In case when address is not relative to any registers, those operators allow
also to choose the appropriate mode of absolute addressing.

Instructions \verb"adc", \verb"add", \verb"and", \verb"cmp",
\verb"or", \verb"sbb", \verb"sub" and \verb"xor" with first
operand being 16--bit or 32--bit are by default generated in
shortened 8--bit form when the second operand is immediate value
fitting in the range for signed 8-bit values. It also can be
overridden by putting the \verb"word" or \verb"dword" operator
before the immediate value. The similar rules applies to the
\verb"imul" instruction with the last operand being immediate
value.

Immediate value as an operand for \verb"push" instruction without a size
operator is by default treated as a word value if assembler is in 16--bit
mode and as a double word value if assembler is in 32--bit mode, shorter
8--bit form of this instruction is used if possible, \verb"word" or
\verb"dword" size operator forces the \verb"push" instruction to be generated
in longer form for specified size. \verb"pushw" and \verb"pushd" mnemonics
force assembler to generate 16-bit or 32--bit code without forcing it to use
the longer form of instruction.

\chapter{Instruction set}
This chapter provides the detailed information about the instructions and
directives supported by flat assembler. Directives for defining labels were
already discussed in \ref{sec:labels}, all other directives will be described later in this chapter.

\section{The x86 architecture instructions}
In this section you can find both the information about the syntax and
purpose the assembly language instructions. If you need more technical
information, look for the Intel Architecture Software Developer's Manual.

Assembly instructions consist of the mnemonic (instruction's name) and from
zero to three operands. If there are two or more operands, usually first is
the destination operand and second is the source operand. Each operand can be
register, memory or immediate value (see \ref{sec:syntax} for details about
syntax of operands). After the description of each instruction there are
examples of different combinations of operands, if the instruction has any.

Some instructions act as prefixes and can be followed by other instruction
in the same line, and there can be more than one prefix in a line. Each name
of the segment register is also a mnemonic of instruction prefix, altough it
is recommended to use segment overrides inside the square brackets instead of
these prefixes.

\subsection{Data movement instructions}
\index{mov}
\verb"mov" transfers a byte, word or double word from the source operand to
the destination operand. It can transfer data between general registers, from
the general register to memory, or from memory to general register, but it
cannot move from memory to memory. It can also transfer an immediate value to
general register or memory, segment register to general register or memory,
general register or memory to segment register, control or debug register to
general register and general register to control or debug register. The
\verb"mov" can be assembled only if the size of source operand and size of
destination operand are the same. Below are the examples for each of the
allowed combinations:
\begin{verbatim}
    mov bx,ax       ; general register to general register
    mov [char],al   ; general register to memory
    mov bl,[char]   ; memory to general register
    mov dl,32       ; immediate value to general register
    mov [char],32   ; immediate value to memory
    mov ax,ds       ; segment register to general register
    mov [bx],ds     ; segment register to memory
    mov ds,ax       ; general register to segment register
    mov ds,[bx]     ; memory to segment register
    mov eax,cr0     ; control register to general register
    mov cr3,ebx     ; general register to control register
\end{verbatim}

\index{xchg}
\verb"xchg" swaps the contents of two operands. It can swap two byte
operands, two word operands or two double word operands. Order of operands is
not important. The operands may be two general registers, or general register
with memory. For example:
\begin{verbatim}
    xchg ax,bx      ; swap two general registers
    xchg al,[char]  ; swap register with memory
\end{verbatim}

\index{push}\index{pushw}\index{pushd}
\verb"push" decrements the stack frame pointer (\verb"esp" register), then
transfers the operand to the top of stack indicated by \verb"esp". The
operand can be memory, general register, segment register or immediate value
of word or double word size. If operand is an immediate value and no size is
specified, it is by default treated as a word value if assembler is in
16--bit mode and as a double word value if assembler is in 32--bit mode.
\verb"pushw" and \verb"pushd" mnemonics are variants of this instruction that
store the values of word or double word size respectively. If more operands
follow in the same line (separated only with spaces, not commas), compiler
will assemble chain of the \verb"push" instructions with these operands.
The examples are with single operands:
\begin{verbatim}
    push ax         ; store general register
    push es         ; store segment register
    pushw [bx]      ; store memory
    push 1000h      ; store immediate value
\end{verbatim}

\index{pusha}\index{pushaw}\index{pushad}
\verb"pusha" saves the contents of the eight general register on the stack.
This instruction has no operands. There are two version of this instruction,
one 16--bit and one 32--bit, assembler automatically generates the right
version for current mode, but it can be overridden by using \verb"pushaw"
or \verb"pushad" mnemonic to always get the 16--bit or 32--bit version.
The 16--bit version of this instruction pushes general registers on the stack
in the following order: \verb"ax", \verb"cx", \verb"dx", \verb"bx", the
initial value of \verb"sp" before \verb"ax" was pushed, \verb"bp", \verb"si"
and \verb"di". The 32--bit version pushes equivalent 32--bit general
registers in the same order.

\index{pop}\index{popw}\index{popd}
\verb"pop" transfers the word or double word at the current top of stack to
the destination operand, and then increments \verb"esp" to point to the new
top of stack. The operand can be memory, general register or segment
register. \verb"popw" and \verb"popd" mnemonics are variants of this
instruction for restoring the values of word or double word size respectively.
If more operands separated with spaces follow in the same line, compiler will
assemble chain of the \verb"pop" instructions with these operands.
\begin{verbatim}
    pop bx          ; restore general register
    pop ds          ; restore segment register
    popw [si]       ; restore memory
\end{verbatim}

\index{popa}\index{popaw}\index{popad}
\verb"popa" restores the registers saved on the stack by \verb"pusha"
instruction, except for the saved value of \verb"sp" (or \verb"esp"),
which is ignored. This instruction has no operands. To force assembling
16--bit or 32--bit version of this instruction use \verb"popaw" or
\verb"popad" mnemonic.

\subsection{Type conversion instructions}
The type conversion instructions convert bytes into words, words into double
words, and double words into quad words. These conversions can be done using
the sign extension or zero extension. The sign extension fills the extra bits
of the larger item with the value of the sign bit of the smaller item,
the zero extension simply fills them with zeros.

\index{cwd}\index{cdq}
\verb"cwd" and \verb"cdq" double the size of value \verb"ax" or \verb"eax"
register respectively and store the extra bits into the \verb"dx" or
\verb"edx" register. The conversion is done using the sign extension.
These instructions have no operands.

\index{cbw}\index{cwde}
\verb"cbw" extends the sign of the byte in \verb"al" throughout \verb"ax",
and \verb"cwde" extends the sign of the word in \verb"ax" throughout
\verb"eax". These instructions also have no operands.

\index{movsx}\index{movzx}
\verb"movsx" converts a byte to word or double word and a word to double word
using the sign extension. \verb"movzx" does the same, but it uses the zero
extension. The source operand can be general register or memory, while the
destination operand must be a general register. For example:
\begin{verbatim}
    movsx ax,al         ; byte register to word register
    movsx edx,dl        ; byte register to double word register
    movsx eax,ax        ; word register to double word register
    movsx ax,byte [bx]  ; byte memory to word register
    movsx edx,byte [bx] ; byte memory to double word register
    movsx eax,word [bx] ; word memory to double word register
\end{verbatim}

\subsection{Binary arithmetic instructions}
\index{add}
\verb"add" replaces the destination operand with the sum of the source and
destination operands and sets CF if overflow has occurred. The operands may
be bytes, words or double words. The destination operand can be general
register or memory, the source operand can be general register or immediate
value, it can also be memory if the destination operand is register.
\begin{verbatim}
    add ax,bx       ; add register to register
    add ax,[si]     ; add memory to register
    add [di],al     ; add register to memory
    add al,48       ; add immediate value to register
    add [char],48   ; add immediate value to memory
\end{verbatim}

\index{adc}
\verb"adc" sums the operands, adds one if CF is set, and replaces the
destination operand with the result. Rules for the operands are the same as
for the \verb"add" instruction. An \verb"add" followed by multiple \verb"adc"
instructions can be used to add numbers longer than 32 bits.

\index{inc}
\verb"inc" adds one to the operand, it does not affect CF. The operand can be
a general register or memory, and the size of the operand can be byte, word or double word.
\begin{verbatim}
    inc ax          ; increment register by one
    inc byte [bx]   ; increment memory by one
\end{verbatim}

\index{sub}
\verb"sub" subtracts the source operand from the destination operand and
replaces the destination operand with the result. If a borrow is required,
the CF is set. Rules for the operands are the same as for the \verb"add"
instruction.

\index{sbb}
\verb"sbb" subtracts the source operand from the destination operand,
subtracts one if CF is set, and stores the result to the destination operand.
Rules for the operands are the same as for the \verb"add" instruction.
A \verb"sub" followed by multiple \verb"sbb" instructions may be used to
subtract numbers longer than 32 bits.

\index{dec}
\verb"dec" subtracts one from the operand, it does not affect CF. Rules for
the operand are the same as for the \verb"inc" instruction.

\index{cmp}
\verb"cmp" subtracts the source operand from the destination operand. It
updates the flags as the \verb"sub" instruction, but does not alter the
source and destination operands. Rules for the operands are the same as for
the \verb"sub" instruction.

\index{neg}
\verb"neg" subtracts a signed integer operand from zero. The effect of this
instructon is to reverse the sign of the operand from positive to negative or
from negative to positive. Rules for the operand are the same as for the
\verb"inc" instruction.

\index{xadd}
\verb"xadd" exchanges the destination operand with the source operand,
then loads the sum of the two values into the destination operand. Rules for
the operands are the same as for the \verb"add" instruction.

All the above binary arithmetic instructions update SF, ZF, PF and OF flags.
SF is always set to the same value as the result's sign bit, ZF is set
when all the bits of result are zero, PF is set when low order eight bits of
result contain an even number of set bits, OF is set if result is too large for a
positive number or too small for a negative number (excluding sign bit) to fit in
destination operand.

\index{mul}
\verb"mul" performs an unsigned multiplication of the operand and the
accumulator. If the operand is a byte, the processor multiplies it by the
contents of \verb"al" and returns the 16--bit result to \verb"ah" and
\verb"al". If the operand is a word, the processor multiplies it by the
contents of \verb"ax" and returns the 32--bit result to \verb"dx" and
\verb"ax". If the operand is a double word, the processor multiplies it by
the contents of \verb"eax" and returns the 64--bit result in \verb"edx" and
\verb"eax". \verb"mul" sets CF and OF when the upper half of the result is
nonzero, otherwise they are cleared. Rules for the operand are the same as
for the \verb"inc" instruction.

\index{imul}
\verb"imul" performs a signed multiplication operation. This
instruction has three variations. First has one operand and
behaves in the same way as the \verb"mul" instruction. Second has
two operands, in this case destination operand is multiplied by
the source operand and the result replaces the destination
operand. Destination operand must be a general register, it can be
word or double word, source operand can be general register,
memory or immediate value. Third form has three operands, the
destination operand must be a general register, word or double
word in size, source operand can be general register or memory,
and third operand must be an immediate value. The source operand
is multiplied by the immediate value and the result is stored in
the destination register. All the three forms calculate the
product to twice the size of operands and set CF and OF when the
upper half of the result is nonzero, but second and third form
truncate the product to the size of operands. So second and third
forms can be also used for unsigned operands because, whether the
operands are signed or unsigned, the lower half of the product is
the same. Below are the examples for all three forms:
\begin{verbatim}
    imul bl         ; accumulator by register
    imul word [si]  ; accumulator by memory
    imul bx,cx      ; register by register
    imul bx,[si]    ; register by memory
    imul bx,10      ; register by immediate value
    imul ax,bx,10   ; register by immediate value to register
    imul ax,[si],10 ; memory by immediate value to register
\end{verbatim}

\index{div}
\verb"div" performs an unsigned division of the accumulator by the operand.
The dividend (the accumulator) is twice the size of the divisor (the
operand), the quotient and remainder have the same size as the divisor.
If divisor is byte, the dividend is taken from \verb"ax" register, the
quotient is stored in \verb"al" and the remainder is stored in \verb"ah".
If divisor is word, the upper half of dividend is taken from \verb"dx",
the lower half of dividend is taken from \verb"ax", the quotient is stored
in \verb"ax" and the remainder is stored in \verb"dx". If divisor is double
word, the upper half of dividend is taken from \verb"edx", the lower half of
dividend is taken from \verb"eax", the quotient is stored in \verb"eax" and
the remainder is stored in \verb"edx". Rules for the operand are the same as
for the \verb"mul" instruction.

\index{idiv}
\verb"idiv" performs a signed division of the accumulator by the operand.
It uses the same registers as the \verb"div" instruction, and the rules for
the operand are the same.

\subsection{Decimal arithmetic instructions}
Decimal arithmetic is performed by combining the binary arithmetic
instructions (already described in the prior section) with the decimal
arithmetic instructions. The decimal arithmetic instructions are used to
adjust the results of a previous binary arithmetic operation to produce a
valid packed or unpacked decimal result, or to adjust the inputs to a
subsequent binary arithmetic operation so the operation will produce a valid
packed or unpacked decimal result.

\index{daa}
\verb"daa" adjusts the result of adding two valid packed decimal operands in
\verb"al". \verb"daa" must always follow the addition of two pairs of packed
decimal numbers (one digit in each half--byte) to obtain a pair of valid
packed decimal digits as results. The carry flag is set if carry was needed.
This instruction has no operands.

\index{das}
\verb"das" adjusts the result of subtracting two valid packed decimal
operands in \verb"al". \verb"das" must always follow the subtraction of one
pair of packed decimal numbers (one digit in each half--byte) from another
to obtain a pair of valid packed decimal digits as results. The carry flag is
set if a borrow was needed. This instruction has no operands.

\index{aaa}
\verb"aaa" changes the contents of register \verb"al" to a valid unpacked
decimal number, and zeroes the top four bits. \verb"aaa" must always follow
the addition of two unpacked decimal operands in \verb"al". The carry flag is
set and \verb"ah" is incremented if a carry is necessary. This instruction
has no operands.

\index{aas}
\verb"aas" changes the contents of register \verb"al" to a valid unpacked
decimal number, and zeroes the top four bits. \verb"aas" must always follow
the subtraction of one unpacked decimal operand from another in \verb"al".
The carry flag is set and \verb"ah" decremented if a borrow is necessary.
This instruction has no operands.

\index{aam}
\verb"aam" corrects the result of a multiplication of two valid unpacked
decimal numbers. \verb"aam" must always follow the multiplication of two
decimal numbers to produce a valid decimal result. The high order digit is
left in \verb"ah", the low order digit in \verb"al". The generalized version
of this instruction allows adjustment of the contents of the \verb"ax" to
create two unpacked digits of any number base. The standard version of this
instruction has no operands, the generalized version has one operand -- an
immediate value specifying the number base for the created digits.

\index{aad}
\verb"aad" modifies the numerator in \verb"ah" and \verb"ah" to prepare for
the division of two valid unpacked decimal operands so that the quotient
produced by the division will be a valid unpacked decimal number. \verb"ah"
should contain the high order digit and \verb"al" the low order digit.
This instruction adjusts the value and places the result in \verb"al", while
\verb"ah" will contain zero. The generalized version of this instruction
allows adjustment of two unpacked digits of any number base. Rules for the
operand are the same as for the \verb"aam" instruction.

\subsection{Logical instructions}
\index{not}
\verb"not" inverts the bits in the specified operand to form a one's
complement of the operand. It has no effect on the flags. Rules for the
operand are the same as for the \verb"inc" instruction.

\index{and}\index{or}\index{xor}
\verb"and", \verb"or" and \verb"xor" instructions perform the standard
logical operations. They update the SF, ZF and PF flags. Rules for the
operands are the same as for the \verb"add" instruction.

\index{bt}\index{bts}\index{btr}\index{btc}
\verb"bt", \verb"bts", \verb"btr" and \verb"btc" instructions operate on a
single bit which can be in memory or in a general register. The location of
the bit is specified as an offset from the low order end of the operand.
The value of the offset is the taken from the second operand, it either may
be an immediate byte or a general register. These instructions first assign
the value of the selected bit to CF. \verb"bt" instruction does nothing more,
\verb"bts" sets the selected bit to 1, \verb"btr" resets the selected bit to
0, \verb"btc" changes the bit to its complement. The first operand can be
word or double word.
\begin{verbatim}
    bt  ax,15        ; test bit in register
    bts word [bx],15 ; test and set bit in memory
    btr ax,cx        ; test and reset bit in register
    btc word [bx],cx ; test and complement bit in memory
\end{verbatim}

\index{bsf}\index{bsr}
\verb"bsf" and \verb"bsr" instructions scan a word or double word for first
set bit and store the index of this bit into destination operand, which must
be general register. The bit string being scanned is specified by source
operand, it may be either general register or memory. The ZF flag is set if
the entire string is zero (no set bits are found); otherwise it is cleared.
If no set bit is found, the value of the destination register is undefined.
\verb"bsf" from low order to high order (starting from bit index zero).
\verb"bsr" scans from high order to low order (starting from bit index 15 of
a word or index 31 of a double word).
\begin{verbatim}
    bsf ax,bx        ; scan register forward
    bsr ax,[si]      ; scan memory reverse
\end{verbatim}

\index{shl}
\verb"shl" shifts the destination operand left by the number of bits
specified in the second operand. The destination operand can be byte, word,
or double word general register or memory. The second operand can be an
immediate value or the \verb"cl" register. The processor shifts zeros in from
the right (low order) side of the operand as bits exit from the left side.
The last bit that exited is stored in CF. \verb"sal" is a synonym for
\verb"shl".
\begin{verbatim}
    shl al,1         ; shift register left by one bit
    shl byte [bx],1  ; shift memory left by one bit
    shl ax,cl        ; shift register left by count from cl
    shl word [bx],cl ; shift memory left by count from cl
\end{verbatim}

\index{shr}\index{sar}
\verb"shr" and \verb"sar" shift the destination operand right by the number
of bits specified in the second operand. Rules for operands are the same as
for the \verb"shl" instruction. \verb"shr" shifts zeros in from the left side
of the operand as bits exit from the right side. The last bit that exited is
stored in CF. \verb"sar" preserves the sign of the operand by shifting in
zeros on the left side if the value is positive or by shifting in ones if the
value is negative.

\index{shld}
\verb"shld" shifts bits of the destination operand to the left by the number
of bits specified in third operand, while shifting high order bits from the
source operand into the destination operand on the right. The source operand
remains unmodified. The destination operand can be a word or double word
general register or memory, the source operand must be a general register,
third operand can be an immediate value or the \verb"cl" register.
\begin{verbatim}
    shld ax,bx,1     ; shift register left by one bit
    shld [di],bx,1   ; shift memory left by one bit
    shld ax,bx,cl    ; shift register left by count from cl
    shld [di],bx,cl  ; shift memory left by count from cl
\end{verbatim}

\index{shrd}
\verb"shrd" shifts bits of the destination operand to the right, while
shifting low order bits from the source operand into the destination operand
on the left. The source operand remains unmodified. Rules for operands are
the same as for the \verb"shld" instruction.

\index{rol}\index{rcl}
\verb"rol" and \verb"rcl" rotate the byte, word or double word destination
operand left by the number of bits specified in the second operand. For each
rotation specified, the high order bit that exits from the left of the
operand returns at the right to become the new low order bit. \verb"rcl"
additionally puts in CF each high order bit that exits from the left side
of the operand before it returns to the operand as the low order bit on the
next rotation cycle. Rules for operands are the same as for the \verb"shl"
instruction.

\index{ror}\index{rcr}
\verb"ror" and \verb"rcr" rotate the byte, word or double word destination
operand right by the number of bits specified in the second operand. For each
rotation specified, the low order bit that exits from the right of the
operand returns at the left to become the new high order bit. \verb"rcr"
additionally puts in CF each low order bit that exits from the right side of
the operand before it returns to the operand as the high order bit on the
next rotation cycle. Rules for operands are the same as for the \verb"shl"
instruction.

\index{test}
\verb"test" performs the same action as the \verb"and" instruction, but it
does not alter the destination operand, only updates flags. Rules for the
operands are the same as for the \verb"and" instruction.

\index{bswap}
\verb"bswap" reverses the byte order of a 32--bit general register:
bits 0 through 7 are swapped with bits 24 through 31, and bits 8 through 15
are swapped with bits 16 through 23. This instruction is provided for
converting little--endian values to big--endian format and vice versa.
\begin{verbatim}
    bswap edx        ; swap bytes in register
\end{verbatim}

\subsection{Control transfer instructions}

\index{jmp}
\verb"jmp" unconditionally transfers control to the target location. The
destination address can be specified directly within the instruction or
indirectly through a register or memory, the acceptable size of this address
depends on whether the jump is near or far (it can be specified by preceding
the operand with \verb"near" or \verb"far" operator) and whether the instruction is
16--bit or 32--bit. Operand for near jump should be \verb"word" size for 16--bit
instruction or the \verb"dword" size for 32--bit instruction. Operand for far jump
should be \verb"dword" size for 16--bit instruction or \verb"pword" size for 32--bit
instruction. A direct \verb"jmp" instruction includes the destination address as
part of the instruction (and can be preceded by \verb"short", \verb"near" or \verb"far"
operator), the operand specifying address should be the numerical expression
for near or short jump, or two numerical expressions separated with colon for
far jump, the first specifies selector of segment, the second is the offset
within segment. The \verb"pword" operator can be used to force the 32--bit far call,
and \verb"dword" to force the 16-bit far call. An indirect \verb"jmp" instruction
obtains the destination address indirectly through a register or a pointer
variable, the operand should be general register or memory. See also \ref{sec:jumps} for
some more details.
\begin{verbatim}
    jmp 100h         ; direct near jump
    jmp 0FFFFh:0     ; direct far jump
    jmp ax           ; indirect near jump
    jmp pword [ebx]  ; indirect far jump
\end{verbatim}

\index{call}
\verb"call" transfers control to the procedure, saving on the stack the
address of the instruction following the \verb"call" for later use by a
\verb"ret" (return) instruction. Rules for the operands are the same as for
the \verb"jmp" instruction, but the \verb"call" has no short variant of
direct instruction and thus it not optimized.

\index{ret}\index{retn}\index{retf}
\index{retw}\index{retnw}\index{retfw}
\index{retd}\index{retnd}\index{retfd}
\verb"ret", \verb"retn" and \verb"retf" instructions terminate the execution
of a procedure and transfers control back to the program that originally
invoked the procedure using the address that was stored on the stack by the
\verb"call" instruction. \verb"ret" is the equivalent for \verb"retn", which
returns from the procedure that was executed using the near call, while
\verb"retf" returns from the procedure that was executed using the far call.
These instructions default to the size of address appropriate for the current
code setting, but the size of address can be forced to 16--bit by using the
\verb"retw", \verb"retnw" and \verb"retfw" mnemonics, and to 32--bit by using
the \verb"retd", \verb"retnd" and \verb"retfd" mnemonics. All these
instructions may optionally specify an immediate operand, by adding this
constant to the stack pointer, they effectively remove any arguments that the
calling program pushed on the stack before the execution of the \verb"call"
instruction.

\index{iret}\index{iretw}\index{iretd}
\verb"iret" returns control to an interrupted procedure. It differs from
\verb"ret" in that it also pops the flags from the stack into the flags
register. The flags are stored on the stack by the interrupt mechanism. It
defaults to the size of return address appropriate for the current code
setting, but it can be forced to use 16--bit or 32--bit address by using the
\verb"iretw" or \verb"iretd" mnemonic.

\index{jo}\index{jno}\index{jc}\index{jb}\index{jnae}\index{jnc}\index{jae}
\index{jnb}\index{je}\index{jz}\index{jne}\index{jnz}\index{jbe}\index{jna}
\index{ja}\index{jnbe}\index{js}\index{jns}\index{jp}\index{jpe}\index{jnp}
\index{jpo}\index{jl}\index{jnge}\index{jge}\index{jnl}\index{jle}\index{jng}
\index{jg}\index{jnle}
The conditional transfer instructions are jumps that may or may not transfer
control, depending on the state of the CPU flags when the instruction
executes. The mnemonics for conditional jumps may be obtained by attaching
the condition mnemonic (see table \ref{tab:conditions}) to the \verb"j"
mnemonic, for example \verb"jc" instruction will transfer the control when
the CF flag is set. The conditional jumps can be short or near, and direct only, and
can be optimized (see \ref{sec:jumps}), the operand should be an immediate
value specifying target address.

\begin{table}[p]
\begin{center}\begin{tabular}{|c|c|c|}
\hline
Mnemonic & Condition tested & Description \\
\hline \hline
\verb"o" & OF = 1 & overflow\\
\hline
\verb"no" & OF = 0 & not overflow\\
\hline
\verb"c" & & carry\\
\verb"b" & CF = 1 & below\\
\verb"nae" & & not above nor equal\\
\hline
\verb"nc" & & not carry\\
\verb"ae" & CF = 0 & above or equal\\
\verb"nb" & & not below\\
\hline
\verb"e" & ZF = 1 & equal\\
\verb"z" & & zero\\
\hline
\verb"ne" & ZF = 0 & not equal\\
\verb"nz" & & not zero\\
\hline
\verb"be" & CF \verb"or" ZF = 1 & below or equal\\
\verb"na" & & not above\\
\hline
\verb"a" & CF \verb"or" ZF = 0 & above\\
\verb"nbe" & & not below nor equal\\
\hline
\verb"s" & SF = 1 & sign\\
\hline
\verb"ns" & SF = 0 & not sign\\
\hline
\verb"p" & PF = 1 & parity\\
\verb"pe" & & parity even\\
\hline
\verb"np" & PF = 0 & not parity\\
\verb"po" & & parity odd\\
\hline
\verb"l" & SF \verb"xor" OF = 1 & less\\
\verb"nge" & & not greater nor equal\\
\hline
\verb"ge" & SF \verb"xor" OF = 0 & greater or equal\\
\verb"nl" & & not less\\
\hline
\verb"le" & (SF \verb"xor" OF) \verb"or" ZF = 1 & less or equal\\
\verb"ng" & & not greater\\
\hline
\verb"g" & (SF \verb"xor" OF) \verb"or" ZF = 0 & greater\\
\verb"nle" & & not less nor equal\\
\hline
\end{tabular}\end{center}
\caption{Conditions.}
\label{tab:conditions}
\end{table}

\index{loop}\index{loopw}\index{loopd}
\index{loope}\index{loopz}\index{loopew}\index{loopzw}\index{looped}\index{loopzd}
\index{loopne}\index{loopnz}\index{loopnew}\index{loopnzw}\index{loopned}\index{loopnzd}
The \verb"loop" instructions are conditional jumps that use a value placed in
\verb"cx" (or \verb"ecx") to specify the number of repetitions of a software
loop. All \verb"loop" instructions automatically decrement \verb"cx" (or
\verb"ecx") and terminate the loop (don't transfer the control) when
\verb"cx" (or \verb"ecx") is zero. It uses \verb"cx" or \verb"ecx" whether
the current code setting is 16--bit or 32--bit, but it can be forced to use
\verb"cx" with the \verb"loopw" mnemonic or to use \verb"ecx" with the
\verb"loopd" mnemonic. \verb"loope" and \verb"loopz" are the synonyms for the
same instruction, which acts as the standard \verb"loop", but also terminates
the loop when ZF flag is set. \verb"loopew" and \verb"loopzw" mnemonics force
them to use \verb"cx" register while \verb"looped" and \verb"loopzd" force
them to use \verb"ecx" register. \verb"loopne" and \verb"loopnz" are the
synonyms for the same instructions, which acts as the standard \verb"loop",
but also terminate the loop when ZF flag is not set. \verb"loopnew" and
\verb"loopnzw" mnemonics force them to use \verb"cx" register while
\verb"loopned" and \verb"loopnzd" force them to use \verb"ecx" register.
Every \verb"loop" instruction needs an operand being an immediate value
specifying target address, it can be only short jump (in the range of 128
bytes back and 127 bytes forward from the address of instruction following
the \verb"loop" instruction).

\index{jcxz}\index{jecxz}
\verb"jcxz" branches to the label specified in the instruction if it finds a
value of zero in \verb"cx", \verb"jecxz" does the same, but checks the value
of \verb"ecx" instead of \verb"cx". Rules for the operands are the same as
for the \verb"loop" instruction.

\index{int}\index{int3}\index{into}
\verb"int" activates the interrupt service routine that corresponds to the
number specified as an operand to the instruction, the number should be in
range from 0 to 255. The interrupt service routine terminates with an
\verb"iret" instruction that returns control to the instruction that follows
\verb"int". \verb"int3" mnemonic codes the short (one byte) trap that invokes
the interrupt 3. \verb"into" instruction invokes the interrupt 4 if the OF
flag is set.

\index{bound}
\verb"bound" verifies that the signed value contained in the specified
register lies within specified limits. An interrupt 5 occurs if the value
contained in the register is less than the lower bound or greater than the
upper bound. It needs two operands, the first operand specifies the register
being tested, the second operand should be memory address for the two signed
limit values. The operands can be \verb"word" or \verb"dword" in size.
\begin{verbatim}
    bound ax,[bx]    ; check word for bounds
    bound eax,[esi]  ; check double word for bounds
\end{verbatim}

\subsection{I/O instructions}

\index{in}
\verb"in" transfers a byte, word, or double word from an input port to
\verb"al", \verb"ax", or \verb"eax". I/O ports can be addressed either
directly, with the immediate byte value coded in instruction, or indirectly
via the \verb"dx" register. The destination operand should be \verb"al",
\verb"ax", or \verb"eax" register. The source operand should be an immediate
value in range from 0 to 255, or \verb"dx" register.
\begin{verbatim}
    in al,20h        ; input byte from port 20h
    in ax,dx         ; input word from port addressed by dx
\end{verbatim}

\index{out}
\verb"out" transfers a byte, word, or double word to an output port from
\verb"al", \verb"ax", or \verb"eax". The program can specify the number of
the port using the same methods as the \verb"in" instruction. The destination
operand should be an immediate value in range from 0 to 255, or \verb"dx"
register. The source operand should be \verb"al", \verb"ax", or \verb"eax"
register.
\begin{verbatim}
    out 20h,ax       ; output word to port 20h
    out dx,al        ; output byte to port addressed by dx
\end{verbatim}

\subsection{Strings operations}

The string operations operate on one element of a string. A string element
may be a byte, a word, or a double word. The string elements are addressed by
\verb"si" and \verb"di" (or \verb"esi" and \verb"edi") registers. After every
string operation \verb"si" and/or \verb"di" (or \verb"esi" and/or \verb"edi")
are automatically updated to point to the next element of the string. If DF
(direction flag) is zero, the index registers are incremented, if DF is one,
they are decremented. The amount of the increment or decrement is 1, 2, or 4
depending on the size of the string element. Every string operation
instruction has short forms which have no operands and use \verb"si" and/or
\verb"di" when the code type is 16--bit, and \verb"esi" and/or \verb"edi"
when the code type is 32--bit. \verb"si" and \verb"esi" by default address
data in the segment selected by \verb"ds", \verb"di" and \verb"edi" always
address data in the segment selected by \verb"es". Short form is obtained
by attaching to the mnemonic of string operation letter specifying the size
of string element, it should be \verb"b" for byte element, \verb"w" for word
element, and \verb"d" for double word element. Full form of string operation
needs operands providing the size operator and the memory addresses, which
can be \verb"si" or \verb"esi" with any segment prefix, \verb"di" or
\verb"edi" always with \verb"es" segment prefix.

\index{movs}\index{movsb}\index{movsw}\index{movsd}
\verb"movs" transfers the string element pointed to by \verb"si" (or
\verb"esi") to the location pointed to by \verb"di" (or \verb"edi"). Size of
operands can be \verb"byte", \verb"word" or \verb"dword". The destination
operand should be memory addressed by \verb"di" or \verb"edi", the source
operand should be memory addressed by \verb"si" or \verb"esi" with any
segment prefix.
\begin{verbatim}
    movs byte [di],[si]        ; transfer byte
    movs word [es:di],[ss:si]  ; transfer word
    movsd                      ; transfer double word
\end{verbatim}

\index{cmps}\index{cmpsb}\index{cmpsw}\index{cmpsd}
\verb"cmps" subtracts the destination string element from the source string
element and updates the flags AF, SF, PF, CF and OF, but it does not change
any of the compared elements. If the string elements are equal, ZF is set,
otherwise it is cleared. The first operand for this instruction should be the
source string element addressed by \verb"si" or \verb"esi" with any segment
prefix, the second operand should be the destination string element addressed
by \verb"di" or \verb"edi".
\begin{verbatim}
    cmpsb                      ; compare bytes
    cmps word [ds:si],[es:di]  ; compare words
    cmps dword [fs:esi],[edi]  ; compare double words
\end{verbatim}

\index{scas}\index{scasb}\index{scasw}\index{scasd}
\verb"scas" subtracts the destination string element from \verb"al",
\verb"ax", or \verb"eax" (depending on the size of string element) and
updates the flags AF, SF, ZF, PF, CF and OF. If the values are equal, ZF is
set, otherwise it is cleared. The operand should be the destination string
element addressed by \verb"di" or \verb"edi".
\begin{verbatim}
    scas byte [es:di]          ; scan byte
    scasw                      ; scan word
    scas dword [es:edi]        ; scan double word
\end{verbatim}

\index{lods}\index{lodsb}\index{lodsw}\index{lodsd}
\verb"lods" places the source string element into \verb"al", \verb"ax", or
\verb"eax". The operand should be the source string element addressed by
\verb"si" or \verb"esi" with any segment prefix.
\begin{verbatim}
    lods byte [ds:si]          ; load byte
    lods word [cs:si]          ; load word
    lodsd                      ; load double word
\end{verbatim}

\index{stos}\index{stosb}\index{stosw}\index{stosd}
\verb"stos" places the value of \verb"al", \verb"ax", or \verb"eax" into the
destination string element. Rules for the operand are the same as for the
\verb"scas" instruction.

\index{ins}\index{insb}\index{insw}\index{insd}
\verb"ins" transfers a byte, word, or double word from an input port
addressed by \verb"dx" register to the destination string element. The
destination operand should be memory addressed by \verb"di" or \verb"edi",
the source operand should be the \verb"dx" register.
\begin{verbatim}
    insb                       ; input byte
    ins word [es:di],dx        ; input word
    ins dword [edi],dx         ; input double word
\end{verbatim}

\index{outs}\index{outsb}\index{outsw}\index{outsd}
\verb"outs" transfers the source string element to an output port addressed
by \verb"dx" register. The destination operand should be the \verb"dx"
register and the source operand should be memory addressed by \verb"si" or
\verb"esi" with any segment prefix.
\begin{verbatim}
    outs dx,byte [si]           ; output byte
    outsw                       ; output word
    outs dx,dword [gs:esi]      ; output double word
\end{verbatim}

\index{rep}\index{repe}\index{repz}\index{repne}\index{repnz}
The repeat prefixes \verb"rep", \verb"repe"/\verb"repz", and
\verb"repne"/\verb"repnz" specify repeated string operation. When a string
operation instruction has a repeat prefix, the operation is executed
repeatedly, each time using a different element of the string. The repetition
terminates when one of the conditions specified by the prefix is satisfied.
All three prefixes automatically decrease \verb"cx" or \verb"ecx" register
(depending whether string operation instruction uses the 16--bit or 32--bit
addressing) after each operation and repeat the associated operation until
\verb"cx" or \verb"ecx" is zero. \verb"repe"/\verb"repz" and
\verb"repne"/\verb"repnz" are used exclusively with the \verb"scas" and
\verb"cmps" instructions (described below). When these prefixes are used,
repetition of the next instruction depends on the zero flag (ZF) also,
\verb"repe" and \verb"repz" terminate the execution when the ZF is zero,
\verb"repne" and \verb"repnz" terminate the execution when the ZF is set.
\begin{verbatim}
    rep  movsd       ; transfer multiple double words
    repe cmpsb       ; compare bytes until not equal
\end{verbatim}

\subsection{Flag control instructions}

The flag control instructions provide a method for directly changing the
state of bits in the flag register. All instructions described in this
section have no operands.

\index{stc}\index{clc}\index{cmc}\index{std}\index{cld}\index{sti}\index{cli}
\verb"stc" sets the CF (carry flag) to 1, \verb"clc" zeroes the CF,
\verb"cmc" changes the CF to its complement. \verb"std" sets the DF
(direction flag) to 1, \verb"cld" zeroes the DF, \verb"sti" sets the IF
(interrupt flag) to 1 and therefore enables the interrupts, \verb"cli" zeroes
the IF and therefore disables the interrupts.

\index{lahf}
\verb"lahf" copies SF, ZF, AF, PF, and CF to bits 7, 6, 4, 2, and 0 of the
\verb"ah" register. The contents of the remaining bits are undefined.
The flags remain unaffected.

\index{sahf}
\verb"sahf" transfers bits 7, 6, 4, 2, and 0 from the \verb"ah" register
into SF, ZF, AF, PF, and CF.

\index{pushf}\index{pushfw}\index{pushfd}
\verb"pushf" decrements \verb"esp" by two or four and stores the low word or
double word of flags register at the top of stack, size of stored data
depends on the current code setting. \verb"pushfw" variant forces storing the
word and \verb"pushfd" forces storing the double word.

\index{popf}\index{popfw}\index{popfd}
\verb"popf" transfers specific bits from the word or double word at the top
of stack, then increments \verb"esp" by two or four, this value depends on
the current code setting. \verb"popfw" variant forces restoring from the word
and \verb"popfd" forces restoring from the double word.

\subsection{Conditional operations}

\index{seto}\index{setno}\index{setc}\index{setb}\index{setnae}\index{setnc}\index{setae}
\index{setnb}\index{sete}\index{setz}\index{setne}\index{setnz}\index{setbe}\index{setna}
\index{seta}\index{setnbe}\index{sets}\index{setns}\index{setp}\index{setpe}\index{setnp}
\index{setpo}\index{setl}\index{setnge}\index{setge}\index{setnl}\index{setle}\index{setng}
\index{setg}\index{setnle}
The instructions obtained by attaching the condition mnemonic (see table
\ref{tab:conditions}) to the \verb"set" mnemonic set a byte to one if the
condition is true and set the byte to zero otherwise. The operand should be
an 8--bit be general register or the byte in memory.
\begin{verbatim}
    setne al         ; set al if zero flag cleared
    seto byte [bx]   ; set byte if overflow
\end{verbatim}

\index{salc}
\verb"salc" instruction sets the all bits of \verb"al" register when the
carry flag is set and zeroes the \verb"al" register otherwise. This
instruction has no arguments.

\index{cmovo}\index{cmovno}\index{cmovc}\index{cmovb}\index{cmovnae}\index{cmovnc}\index{cmovae}
\index{cmovnb}\index{cmove}\index{cmovz}\index{cmovne}\index{cmovnz}\index{cmovbe}\index{cmovna}
\index{cmova}\index{cmovnbe}\index{cmovs}\index{cmovns}\index{cmovp}\index{cmovpe}\index{cmovnp}
\index{cmovpo}\index{cmovl}\index{cmovnge}\index{cmovge}\index{cmovnl}\index{cmovle}\index{cmovng}
\index{cmovg}\index{cmovnle}
The instructions obtained by attaching the condition mnemonic to
\verb"cmov" mnemonic transfer the word or double word from the general
register or memory to the general register only when the condition is true.
The destination operand should be general register, the source operand can be
general register or memory.
\begin{verbatim}
    cmove ax,bx      ; move when zero flag set
    cmovnc eax,[ebx] ; move when carry flag cleared
\end{verbatim}

\index{cmpxchg}
\verb"cmpxchg" compares the value in the \verb"al", \verb"ax", or \verb"eax"
register with the destination operand. If the two values are equal,
the source operand is loaded into the destination operand. Otherwise,
the destination operand is loaded into the \verb"al", \verb"ax", or \verb"eax"
register. The destination operand may be a general register or memory, the
source operand must be a general register.
\begin{verbatim}
    cmpxchg dl,bl    ; compare and exchange with register
    cmpxchg [bx],dx  ; compare and exchange with memory
\end{verbatim}

\index{cmpxchg8b}
\verb"cmpxchg8b" compares the 64--bit value in \verb"edx" and \verb"eax"
registers with the destination operand. If the values are equal, the 64--bit
value in \verb"ecx" and \verb"ebx" registers is stored in the destination
operand. Otherwise, the value in the destination operand is loaded into
\verb"edx" and \verb"eax" registers. The destination operand should be a
quad word in memory.
\begin{verbatim}
    cmpxchg8b [bx]   ; compare and exchange 8 bytes
\end{verbatim}

\subsection{Miscellaneous instructions}

\index{nop}
\verb"nop" instruction occupies one byte but affects nothing but the
instruction pointer. This instruction has no operands and doesn't perform any
operation.

\index{ud2}
\verb"ud2" instruction generates an invalid opcode exception. This
instruction is provided for software testing to explicitly generate an
invalid opcode. This is instruction has no operands.

\index{xlat}
\verb"xlat" replaces a byte in the \verb"al" register with a byte indexed by
its value in a translation table addressed by \verb"bx" or \verb"ebx". The
operand should be a byte memory addressed by \verb"bx" or \verb"ebx" with any
segment prefix. This instruction has also a short form \verb"xlatb" which has
no operands and uses the \verb"bx" or \verb"ebx" address in the segment
selected by \verb"ds" depending on the current code setting.

\index{lds}\index{les}\index{lfs}\index{lgs}\index{lss}
\verb"lds" transfers a pointer variable from the source operand to \verb"ds"
and the destination register. The source operand must be a memory operand,
and the destination operand must be a general register. The \verb"ds"
register receives the segment selector of the pointer while the destination
register receives the offset part of the pointer. \verb"les", \verb"lfs",
\verb"lgs" and \verb"lss" operate identically to \verb"lds" except that
rather than \verb"ds" register the \verb"es", \verb"fs", \verb"gs" and
\verb"ss" is used respectively.
\begin{verbatim}
    lds bx,[si]      ; load pointer to ds:bx
\end{verbatim}

\index{lea}
\verb"lea" transfers the offset of the source operand (rather than its value)
to the destination operand. The source operand must be a memory operand, and
the destination operand must be a general register.
\begin{verbatim}
    lea dx,[bx+si+1] ; load effective address to dx
\end{verbatim}

\index{cpuid}
\verb"cpuid" returns processor identification and feature information in the
\verb"eax", \verb"ebx", \verb"ecx", and \verb"edx" registers. The information
returned is selected by entering a value in the \verb"eax" register before
the instruction is executed. This instruction has no operands.

\index{pause}
\verb"pause" instruction delays the execution of the next instruction an
implementation specific amount of time. It can be used to improve the
performance of spin wait loops. This instruction has no operands.

\index{enter}\index{leave}
\verb"enter" creates a stack frame that may be used to implement the scope
rules of block--structured high--level languages. A \verb"leave" instruction
at the end of a procedure complements an \verb"enter" at the beginning of the
procedure to simplify stack management and to control access to variables for
nested procedures. The \verb"enter" instruction includes two parameters. The
first parameter specifies the number of bytes of dynamic storage to be
allocated on the stack for the routine being entered. The second parameter
corresponds to the lexical nesting level of the routine, it can be in range
from 0 to 31. The specified lexical level determines how many sets of stack
frame pointers the CPU copies into the new stack frame from the preceding
frame. This list of stack frame pointers is sometimes called the display.
The first word (or double word when code is 32--bit) of the display is a
pointer to the last stack frame. This pointer enables a \verb"leave"
instruction to reverse the action of the previous \verb"enter" instruction by
effectively discarding the last stack frame. After \verb"enter" creates the
new display for a procedure, it allocates the dynamic storage space for that
procedure by decrementing \verb"esp" by the number of bytes specified in the
first parameter. To enable a procedure to address its display, \verb"enter"
leaves \verb"bp" (or \verb"ebp") pointing to the beginning of the new stack
frame. If the lexical level is zero, \verb"enter" pushes \verb"bp" (or
\verb"ebp"), copies \verb"sp" to \verb"bp" (or \verb"esp" to \verb"ebp") and
then subtracts the first operand from \verb"esp". For nesting levels greater
than zero, the processor pushes additional frame pointers on the stack before
adjusting the stack pointer.
\begin{verbatim}
    enter 2048,0     ; enter and allocate 2048 bytes on stack
\end{verbatim}

\subsection{System instructions}

\index{lmsw}\index{smsw}
\verb"lmsw" loads the operand into the machine status word (bits 0 through 15
of \verb"cr0" register), while \verb"smsw" stores the machine status word
into the destination operand. The operand for both those instructions can be 16--bit
general register or memory, for \verb"smsw" it can also be 32--bit general
register.
\begin{verbatim}
    lmsw ax          ; load machine status from register
    smsw [bx]        ; store machine status to memory
\end{verbatim}

\index{lgdt}\index{lidt}\index{sgdt}\index{sidt}
\verb"lgdt" and \verb"lidt" instructions load the values in operand into the
global descriptor table register or the interrupt descriptor table register
respectively. \verb"sgdt" and \verb"sidt" store the contents of the global
descriptor table register or the interrupt descriptor table register
in the destination operand. The operand should be a 6 bytes in memory.
\begin{verbatim}
    lgdt [ebx]       ; load global descriptor table
\end{verbatim}

\index{lldt}\index{sldt}\index{ltr}\index{str}
\verb"lldt" loads the operand into the segment selector field of
the local descriptor table register and \verb"sldt" stores the
segment selector from the local descriptor table register in the
operand. \verb"ltr" loads the operand into the segment selector
field of the task register and \verb"str" stores the segment
selector from the task register in the operand. Rules for operand
are the same as for the \verb"lmsw" and \verb"smsw" instructions.

\index{lar}
\verb"lar" loads the access rights from the segment descriptor
specified by the selector in source operand into the destination
operand and sets the ZF flag. The destination operand can be a
16-bit or 32--bit general register. The source operand should be a
16-bit general register or memory.
\begin{verbatim}
    lar ax,[bx]      ; load access rights into word
    lar eax,dx       ; load access rights into double word
\end{verbatim}

\index{lsl}
\verb"lsl" loads the segment limit from the segment descriptor specified by
the selector in source operand into the destination operand and sets the ZF
flag. Rules for operand are the same as for the \verb"lar" instruction.

\index{verr}\index{verw}
\verb"verr" and \verb"verw" verify whether the code or data segment specified
with the operand is readable or writable from the current privilege level.
The operand should be a word, it can be general register or memory.
If the segment is accessible and readable (for \verb"verr") or writable (for
\verb"verw") the ZF flag is set, otherwise it's cleared. Rules for operand
are the same as for the \verb"lldt" instruction.

\index{arpl}
\verb"arpl" compares the RPL (requestor's privilege level) fields of two
segment selectors. The first operand contains one segment selector and the
second operand contains the other. If the RPL field of the destination
operand is less than the RPL field of the source operand, the ZF flag is set
and the RPL field of the destination operand is increased to match that of
the source operand. Otherwise, the ZF flag is cleared and no change is made
to the destination operand. The destination operand can be a word general
register or memory, the source operand must be a general register.
\begin{verbatim}
    arpl bx,ax       ; adjust RPL of selector in register
    arpl [bx],ax     ; adjust RPL of selector in memory
\end{verbatim}

\index{clts}
\verb"clts" clears the TS (task switched) flag in the \verb"cr0" register.
This instruction has no operands.

\index{lock}
\verb"lock" prefix causes the processor's bus--lock signal to be asserted during
execution of the accompanying instruction. In a multiprocessor environment,
the bus--lock signal insures that the processor has exclusive use of any shared
memory while the signal is asserted. The \verb"lock" prefix can be prepended
only to the following instructions and only to those forms of the
instructions where the destination operand is a memory operand: \verb"add",
\verb"adc", \verb"and", \verb"btc", \verb"btr", \verb"bts", \verb"cmpxchg",
\verb"cmpxchg8b", \verb"dec", \verb"inc", \verb"neg", \verb"not", \verb"or",
\verb"sbb", \verb"sub", \verb"xor", \verb"xadd" and \verb"xchg". If the
\verb"lock" prefix is used with one of these instructions and the source
operand is a memory operand, an undefined opcode exception may be generated.
An undefined opcode exception will also be generated if the \verb"lock"
prefix is used with any instruction not in the above list. The \verb"xchg"
instruction always asserts the bus--lock signal regardless of the presence or
absence of the \verb"lock" prefix.

\index{hlt}
\verb"hlt" stops instruction execution and places the processor in a halted
state. An enabled interrupt, a debug exception, the BINIT, INIT or the RESET
signal will resume execution. This instruction has no operands.

\index{invlpg}
\verb"invlpg" invalidates (flushes) the TLB (translation lookaside buffer)
entry specified with the operand, which should be a memory. The processor
determines the page that contains that address and flushes the TLB entry for
that page.

\index{rdmsr}\index{wrmsr}
\verb"rdmsr" loads the contents of a 64--bit MSR (model specific register)
of the address specified in the \verb"ecx" register into registers \verb"edx"
and \verb"eax". \verb"wrmsr" writes the contents of registers \verb"edx" and
\verb"eax" into the 64--bit MSR of the address specified in the \verb"ecx"
register. \verb"rdtsc" loads the current value of the processor's time stamp
counter from the 64--bit MSR into the \verb"edx" and \verb"eax" registers.
The processor increments the time stamp counter MSR every clock cycle and
resets it to 0 whenever the processor is reset.

\index{rdpmc}
\verb"rdpmc" loads the contents of the 40--bit performance monitoring counter
specified in the \verb"ecx" register into registers \verb"edx" and
\verb"eax". These instructions have no operands.

\index{wbinvd}
\verb"wbinvd" writes back all modified cache lines in the processor's
internal cache to main memory and invalidates (flushes) the internal caches.
The instruction then issues a special function bus cycle that directs
external caches to also write back modified data and another bus cycle to
indicate that the external caches should be invalidated. This instruction has
no operands.

\index{rsm}
\verb"rsm" return program control from the system management mode to the
program that was interrupted when the processor received an SMM interrupt.
This instruction has no operands.

\index{sysenter}\index{sysexit}
\verb"sysenter" executes a fast call to a level 0 system procedure, \verb"sysexit"
executes a fast return to level 3 user code. The addresses used by these instructions
are stored in MSRs. These instructions have no operands.

\subsection{FPU instructions}

The FPU (Floating-Point Unit) instructions operate on the floating--point
values in three formats: single precision (32--bit), double precision
(64--bit) and double extended precision (80--bit). The FPU registers form
the stack and each of them holds the double extended precision floating--point
value. When some values are pushed onto the stack or are removed from the top,
the FPU registers are shifted, so \verb"st0" is always the value on
the top of FPU stack, \verb"st1" is the first value below the top, etc.
The \verb"st0" name has also the synonym \verb"st".

\index{fld}
\verb"fld" pushes the floating--point value onto the FPU register stack.
The operand can be 32--bit, 64--bit or 80--bit memory location or the
FPU register, its value is then loaded onto the top of FPU register stack
(the \verb"st0" register) and is automatically converted into the
double extended precision format.
\begin{verbatim}
    fld dword [bx]   ; load single prevision value from memory
    fld st2          ; push value of st2 onto register stack
\end{verbatim}

\index{fld1}\index{lfdz}\index{ldl2t}\index{lfdl2e}\index{fldpi}
\index{fldlg2}\index{fldln2}
\verb"fld1", \verb"fldz", \verb"fldl2t", \verb"fldl2e", \verb"fldpi",
\verb"fldlg2" and \verb"fldln2" load the commonly used contants onto the
FPU register stack. The loaded constants are $+1.0$, $+0.0$, $\log_{2}10$,
$\log_{2}e$, $\pi$, $\log_{10}2$ and $\ln{2}$ respectively. These instructions
have no operands.

\index{fild}
\verb"fild" converts the signed integer source operand into double extended
precision floating-point format and pushes the result onto the FPU register
stack. The source operand can be a 16--bit, 32--bit or 64--bit memory location.
\begin{verbatim}
    fild qword [bx]  ; load 64-bit integer from memory
\end{verbatim}

\index{fst}\index{fstp}
\verb"fst" copies the value of \verb"st0" register to the destination operand,
which can be 32--bit or 64--bit memory location or another FPU register.
\verb"fstp" performs the same operation as \verb"fst" and then pops the register
stack, getting rid of \verb"st0". \verb"fstp" accepts the same operands as
the \verb"fst" instruction and can also store value in the 80--bit memory.
\begin{verbatim}
    fst st3          ; copy value of st0 into st3 register
    fstp tword [bx]  ; store value in memory and pop stack
\end{verbatim}

\index{fist}
\verb"fist" converts the value in \verb"st0" to a signed integer and stores
the result in the destination operand. The operand can be 16--bit or
32--bit memory location. \verb"fistp" performs the same operation and then
pops the register stack, it accepts the same operands as the \verb"fist"
instruction and can also store integer value in the 64--bit memory, so it
has the same rules for operands as \verb"fild" instruction.

\index{fbld}
\verb"fbld" converts the packed BCD integer into double extended precision
floating--point format and pushes this value onto the FPU stack. \verb"fbstp"
converts the value in \verb"st0" to an 18--digit packed BCD integer, stores the
result in the destination operand, and pops the register stack. The operand
should be an 80--bit memory location.

\index{fadd}
\verb"fadd" adds the destination and source operand and stores the sum in the
destination location. The destination operand is always an FPU register, if the
source is a memory location, the destination is \verb"st0" register and only
source operand should be specified. If both operands are FPU registers, at
least one of them should be \verb"st0" register. An operand in memory can be
a 32--bit or 64--bit value.
\begin{verbatim}
    fadd qword [bx]  ; add double precision value to st0
    fadd st2,st0     ; add st0 to st2
\end{verbatim}

\index{faddp}
\verb"faddp" adds the destination and source operand, stores the sum in the
destination location and then pops the register stack. The destination operand
must be an FPU register and the source operand must be the \verb"st0". When
no operands are specified, \verb"st1" is used as a destination operand.
\begin{verbatim}
    faddp            ; add st0 to st1 and pop the stack
    faddp st2,st0    ; add st0 to st2 and pop the stack
\end{verbatim}

\index{fiadd}
\verb"fiadd" instruction converts an integer source operand into double
extended precision floating--point value and adds it to the destination
operand. The operand should be a 16--bit or 32--bit memory location.
\begin{verbatim}
    fiadd word [bx]  ; add word integer to st0
\end{verbatim}

\index{fsub}\index{fsubr}\index{fmul}\index{fdiv}\index{fdivr}
\verb"fsub", \verb"fsubr", \verb"fmul", \verb"fdiv", \verb"fdivr" instruction
are similar to \verb"fadd", have the same rules for operands and differ only in
the perfomed computation. \verb"fsub" substracts the source operand from the
destination operand, \verb"fsubr" substract the destination operand from the
source operand, \verb"fmul" multiplies the destination and source operands,
\verb"fdiv" divides the destination operand by the source operand and \verb"fdivr"
divides the source operand by the destination operand. \verb"fsubp", \verb"fsubrp",
\verb"fmulp", \verb"fdivp", \verb"fdivrp" perform the same operations and pop the
register stack, the rules for operand are the same as for the \verb"faddp"
instruction. \verb"fisub", \verb"fisubr", \verb"fimul", \verb"fidiv", \verb"fidivr"
perform these operations after converting the integer source operand into
floating--point value, they have the same rules for operands as \verb"fiadd"
instruction.

\index{fsqrt}\index{fsin}\index{fcos}\index{fchs}\index{fabs}\index{frndint}
\index{f2xm1}
\verb"fsqrt" computes the square root of the value in \verb"st0" register,
\verb"fsin" computes the sine of that value, \verb"fcos" computes the cosine
of that value, \verb"fchs" complements its sign bit, \verb"fabs" clears its sign to
create the absolute value, \verb"frndint" rounds it to the nearest integral value,
depending on the current rounding mode. \verb"f2xm1" computes the exponential value
of 2 to the power of \verb"st0" and substracts the $1.0$ from it, the value of
\verb"st0" must lie in the range $-1.0$ to $+1.0$.
All these instruction store the result in \verb"st0" and have no operands.

\index{fsincos}\index{fptan}\index{fpatan}\index{fyl2x}\index{fyl2xp1}
\index{fprem}\index{fprem1}\index{fscale}\index{fxtract}\index{fnop}
\verb"fsincos" computes both the sine and the cosine of the value in
\verb"st0" register, stores the sine in \verb"st0" and pushes the cosine on the
top of FPU register stack. \verb"fptan" computes the tangent of the value in
\verb"st0", stores the result in \verb"st0" and pushes a $1.0$ onto the FPU register
stack. \verb"fpatan" computes the arctangent of the value in \verb"st1" divided by
the value in \verb"st0", stores the result in \verb"st1" and pops the FPU register
stack. \verb"fyl2x" computes the binary logarithm of \verb"st0", multiplies it by
\verb"st1", stores the result in \verb"st1" and pops the FPU register stack;
\verb"fyl2xp1" performs the same operation but it adds $1.0$ to \verb"st0" before
computing the logarithm. \verb"fprem" computes the remainder obtained from
dividing the value in \verb"st0" by the value in \verb"st1", and stores the result
in \verb"st0". \verb"fprem1" performs the same operation as \verb"fprem", but it
computes the remainder in the way specified by IEEE Standard 754. \verb"fscale"
truncates the value in \verb"st1" and increases the exponent of \verb"st0" by this value.
\verb"fxtract" separates the value in \verb"st0" into its exponent and significand,
stores the exponent in \verb"st0" and pushes the significand onto the register
stack. \verb"fnop" performs no operation. These instruction have no operands.

\index{fxch}
\verb"fxch" exchanges the contents of \verb"st0" an another FPU register. The
operand should be an FPU register, if no operand is specified, the contents of
\verb"st0" and \verb"st1" are exchanged.

\index{fcom}\index{fcomp}
\verb"fcom" and \verb"fcomp" compare the contents of \verb"st0" and the source
operand and set flags in the FPU status word according to the results.
\verb"fcomp" additionally pops the register stack after performing the comparison.
The operand can be a single or double precision value in memory or the FPU register.
When no operand is specified, \verb"st1" is used as a source operand.
\begin{verbatim}
    fcom             ; compare st0 with st1
    fcomp st2        ; compare st0 with st2 and pop stack
\end{verbatim}

\index{fcompp}
\verb"fcompp" compares the contents of \verb"st0" and \verb"st1", sets flags in the
FPU status word according to the results and pops the register stack twice.
This instruction has no operands.

\index{fucom}\index{fucomp}\index{fucompp}
\verb"fucom", \verb"fucomp" and \verb"fucompp" performs an unordered comparison of
two FPU registers. Rules for operands are the same as for the \verb"fcom",
\verb"fcomp" and \verb"fcompp", but the source operand must be an FPU register.

\index{ficom}\index{ficomp}
\verb"ficom" and \verb"ficomp" compare the value in \verb"st0" with an integer
source operand and set the flags in the FPU status word according to the results.
\verb"ficomp" additionally pops the register stack after performing the comparison.
The integer value is converted to double extended precision floating--point format
before the comparison is made. The operand should be a 16--bit or 32--bit memory
location.
\begin{verbatim}
    ficom word [bx]  ; compare st0 with 16-bit integer
\end{verbatim}

\index{fcomi}\index{fcomip}\index{fucomi}\index{fucomip}
\verb"fcomi", \verb"fcomip", \verb"fucomi", \verb"fucomip" perform the comparison
of \verb"st0" with another FPU register and set the ZF, PF and CF flags according to
the results. \verb"fcomip" and \verb"fucomip" additionaly pop the register stack
after performing the comparison.

\index{fcmovb}\index{fcmove}\index{fcmovbe}\index{fcmovu}
\index{fcmovnb}\index{fcmovne}\index{fcmovnbe}\index{fcmovnu}
The instructions obtained by attaching the FPU
condition mnemonic (see table \ref{tab:FPU_conditions}) to the \verb"fcmov" mnemonic
transfer the specified FPU register into \verb"st0" register if the given test
condition is true. These instruction allow two different syntaxes, one with single
operand specifying the source FPU register, and one with two operands, in that case
destination operand should be \verb"st0" register and the second operand specifies
the source FPU register.
\begin{verbatim}
    fcomi st2        ; compare st0 with st2 and set flags
    fcmovb st0,st2   ; transfer st2 to st0 if below
\end{verbatim}

\label{tab:FPU_conditions}
\begin{table}[hbt]
\caption{FPU conditions.}
\begin{center}\begin{tabular}{|c|c|c|}
\hline
Mnemonic & Condition tested & Description \\
\hline \hline
\verb"b" & CF = 1 & below\\
\hline
\verb"e" & ZF = 1 & equal\\
\hline
\verb"be" & CF \verb"or" ZF = 1 & below or equal\\
\hline
\verb"u" & PF = 1 & unordered\\
\hline
\verb"nb" & CF = 0 & not below\\
\hline
\verb"ne" & ZF = 0 & not equal\\
\hline
\verb"nbe" & CF \verb"and" ZF = 0 & not below nor equal\\
\hline
\verb"nu" & PF = 0 & not unordered\\
\hline
\end{tabular}\end{center}
\end{table}

\index{ftst}\index{fxam}
\verb"ftst" compares the value in \verb"st0" with $0.0$ and sets the flags in the
FPU status word according to the results. \verb"fxam" examines the contents of the
\verb"st0" and sets the flags in FPU status word to indicate the class of value in
the register. These instructions have no operands.

\index{fstsw}\index{fnstsw}
\verb"fstsw" and \verb"fnstsw" store the current value of the FPU status word in the
destination location. The destination operand can be either a 16--bit memory or the
\verb"ax" register. \verb"fstsw" checks for pending umasked FPU exceptions before
storing the status word, \verb"fnstsw" does not.

\index{fstcw}\index{fnstcw}
\verb"fstcw" and \verb"fnstcw" store the current value of the FPU control word
at the specified destination in memory. \verb"fstcw" checks for pending unmasked FPU
exceptions before storing the control word, \verb"fnstcw" does not. \verb"fldcw" loads
the operand into the FPU control word. The operand should be a 16--bit memory
location.

\index{fstenv}\index{fnstenv}\index{fldenv}\index{fsave}\index{fnsave}\index{frstor}
\index{fstenvw}\index{fnstenvw}\index{fldenvw}\index{fsavew}\index{fnsavew}\index{frstorw}
\index{fstenvd}\index{fnstenvd}\index{fldenvd}\index{fsaved}\index{fnsaved}\index{frstord}
\verb"fstenv" and \verb"fnstenv" store the current FPU operating environment at
the memory location specified with the destination operand, and then mask all
FPU exceptions. \verb"fstenv" checks for pending umasked FPU exceptions before
proceeding, \verb"fnstenv" does not. \verb"fldenv" loads the complete operating
environment from memory into the FPU. \verb"fsave" and \verb"fnsave"
store the current FPU state (operating environment and register stack) at the
specified destination in memory and reinitializes the FPU. \verb"fsave" check
for pending unmasked FPU exceptions before proceeding, \verb"fnsave" does not.
\verb"frstor" loads the FPU state from the specified memory location.
All these instructions need an operand being a memory location.
For each of these instruction
exist two additional mnemonics that allow to precisely select the type of the
operation. The \verb"fstenvw", \verb"fnstenvw", \verb"fldenvw", \verb"fsavew", \verb"fnsavew" and
\verb"frstorw" mnemonics force the instruction to perform operation as in the 16--bit
mode, while \verb"fstenvd", \verb"fnstenvd", \verb"fldenvd", \verb"fsaved", \verb"fnsaved" and \verb"frstord"
force the operation as in 32--bit mode.

\index{finit}\index{fninit}\index{fclex}\index{fnclex}\index{wait}\index{fwait}
\verb"finit" and \verb"fninit" set the FPU operating environment into its default
state. \verb"finit" checks for pending unmasked FPU exception before proceeding,
\verb"fninit" does not. \verb"fclex" and \verb"fnclex" clear the FPU exception flags in the FPU
status word. \verb"fclex" checks for pending unmasked FPU exception before proceeding,
\verb"fnclex" does not. \verb"wait" and \verb"fwait" are synonyms for the same
instruction, which causes the processor to check for pending unmasked FPU exceptions
and handle them before proceeding. These instruction have no operands.

\index{ffree}
\verb"ffree" sets the tag associated with specified FPU register to empty. The
operand should be an FPU register.

\index{fincstp}\index{fdecstp}
\verb"fincstp" and \verb"fdecstp" rotate the FPU stack by one by adding or
substracting one to the pointer of the top of stack. These instruction have no
operands.

\subsection{MMX instructions}
\label{sec:MMX_instructions}

The MMX instructions operate on the packed integer types and use the MMX registers,
which are the low 64--bit parts of the 80--bit FPU registers. Because of this MMX
instructions cannot be used at the same time as FPU instructions. They can operate
on packed bytes (eight 8--bit integers), packed words (four 16--bit integers) or
packed double words (two 32--bit integers), use of packed formats allows to perform
operations on multiple data at one time.

\index{movq}
\verb"movq" copies a quad word from the source operand to the destination operand.
At least one of the operands must be a MMX register, the second one can be also
a MMX register or 64--bit memory location.
\begin{verbatim}
    movq mm0,mm1     ; move quad word from register to register
    movq mm2,[ebx]   ; move quad word from memory to register
\end{verbatim}

\index{movd}
\verb"movd" copies a double word from the source operand to the destination operand.
One of the operands must be a MMX register, the second one can be a general register
or 32--bit memory location. Only low double word of MMX register is used.

All general MMX operations have two operands, the destination operand should be
a MMX register, the source operand can be a MMX register or 64--bit memory location.
Operation is performed on the corresponding data elements of the source and destination
operand and stored in the data elements of the destination operand.

\index{paddb}\index{paddw}\index{paddd}
\verb"paddb", \verb"paddw" and \verb"paddd" perform the addition of packed bytes,
packed words, or packed double words.  

\index{psubb}\index{psubw}\index{psubd}
\verb"psubb", \verb"psubw" and \verb"psubd" perform the substraction of appropriate types. 

\index{paddsb}\index{paddsw}\index{psubsb}\index{psubsw}
\verb"paddsb", \verb"paddsw", \verb"psubsb" and \verb"psubsw" perform the addition or 
substraction of packed bytes or packed words with the signed saturation. 

\index{paddusb}\index{paddusw}\index{psubusb}\index{psubusw}
\verb"paddusb", \verb"paddusw", \verb"psubusb", \verb"psubusw" are analoguous, but with 
unsigned saturation.

\index{pmulhw}\index{pmullw}\
\verb"pmulhw" and \verb"pmullw" performs a signed multiplication of the packed words
and store the high or low words of the results in the destination operand.

\index{pmaddwd}
\verb"pmaddwd" performs a multiply of the packed words and adds the four intermediate
double word products in pairs to produce result as a packed double words.

\index{pand}\index{por}\index{pxor}\index{pandn}
\verb"pand", \verb"por" and \verb"pxor" perform the logical operations on the quad words,
\verb"pandn" peforms also a logical negation of the destination operand before the
operation.

\index{pcmpeqb}\index{pcmpeqw}\index{pcmpeqd}
\verb"pcmpeqb", \verb"pcmpeqw" and \verb"pcmpeqd" compare for equality of packed
bytes, packed words or packed double words. If a pair of data elements is equal,
the corresponding data element in the destination operand is filled with bits of
value 1, otherwise it's set to 0. 

\index{pcmpgtb}\index{pcmpgtw}\index{pcmpgtd}
\verb"pcmpgtb", \verb"pcmpgtw" and \verb"pcmpgtd"
perform the similar operation, but they check whether the data elements in
the destination operand are greater than the correspoding data elements in the
source operand.

\index{packsswb}\index{packssdw}\index{packuswb}
\verb"packsswb" converts packed signed words into packed signed bytes, \verb"packssdw"
converts packed signed double words into packed signed words, using saturation to
handle overflow conditions. \verb"packuswb" converts packed signed words into
packed unsigned bytes. Converted data elements from the source operand are stored
in the low part of the destination operand, while converted data elements from
the destination operand are stored in the high part.

\index{punpckhbw}\index{punpckhwd}\index{punpckhdq}
\verb"punpckhbw", \verb"punpckhwd" and \verb"punpckhdq" interleaves the
data elements from the high parts of the source and destination operands and stores
the result into the destination operand. 

\index{punpcklbw}\index{punpcklwd}\index{punpckldq}
\verb"punpcklbw", \verb"punpcklwd" and
\verb"punpckldq" perform the same operation, but the low parts of the source and destination
operand are used.
\begin{verbatim}
    paddsb mm0,[esi] ; add packed bytes with signed saturation
    pcmpeqw mm3,mm7  ; compare packed words for equality
\end{verbatim}

\index{psllw}\index{pslld}\index{psllq}
\verb"psllw", \verb"pslld" and \verb"psllq" perform logical shift left of the packed
words, packed double words or a single quad word in the destination operand by the
amount specified in the source operand. 

\index{psrlw}\index{psrld}\index{psrlq}
\verb"psrlw", \verb"psrld" and \verb"psrlq" perform logical shift right of the packed words, 
packed double words or a single quad word. 

\index{psraw}\index{psrad}
\verb"psraw" and \verb"psrad" perform arithmetic shift of the packed words or
double words. The destination operand should be a MMX register, while source operand
can be a MMX register, 64--bit memory location, or 8--bit immediate value.
\begin{verbatim}
    psllw mm2,mm4    ; shift words left logically
    psrad mm4,[ebx]  ; shift double words right arithmetically
\end{verbatim}

\index{emms}
\verb"emms" makes the FPU registers usable for the FPU instructions, it must be used
before using the FPU instructions if any MMX instructions were used.

\subsection{SSE instructions}
The SSE extension adds more MMX instructions and also introduces the
operations on packed single precision floating point values. The 128--bit
packed single precision format consists of four single precision floating
point values. The 128--bit SSE registers are designed for the purpose of
operations on this data type.

\index{movaps}\index{movups}
\verb"movaps" and \verb"movups" transfer a double quad word operand containing packed
single precision values from source operand to destination operand. At least
one of the operands have to be a SSE register, the second one can be also a
SSE register or 128--bit memory location. Memory operands for \verb"movaps"
instruction must be aligned on boundary of 16 bytes, operands for \verb"movups"
instruction don't have to be aligned.
\begin{verbatim}
    movups xmm0,[ebx]  ; move unaligned double quad word
\end{verbatim}

\index{movlps}\index{movhps}
\verb"movlps" moves packed two single precision values between the memory and the
low quad word of SSE register. \verb"movhps" moved packed two single precision
values between the memory and the high quad word of SSE register. One of the
operands must be a SSE register, and the other operand must be a 64--bit memory
location.
\begin{verbatim}
    movlps xmm0,[ebx]  ; move memory to low quad word of xmm0
    movhps [esi],xmm7  ; move high quad word of xmm7 to memory
\end{verbatim}

\index{movlhps}\index{movhlps}
\verb"movlhps" moves packed two single precision values from the low quad word
of source register to the high quad word of destination register. \verb"movhlps"
moves two packed single precision values from the high quad word of source
register to the low quad word of destination register. Both operands have to
be a SSE registers.

\index{movmskps}
\verb"movmskps" transfers the most significant bit of each of the four single
precision values in the SSE register into low four bits of a general register.
The source operand must be a SSE register, the destination operand must be a
general register.

\index{movss}
\verb"movss" transfers a single precision value between source and destination
operand (only the low double word is trasferred). At least one of the operands
have to be a SSE register, the second one can be also a SSE register or 32--bit
memory location.
\begin{verbatim}
    movss [edi],xmm3   ; move low double word of xmm3 to memory
\end{verbatim}

Each of the SSE arithmetic operations has two variants. When the mnemonic
ends with \verb"ps", the source operand can be a 128--bit memory location or a SSE
register, the destination operand must be a SSE register and the operation is
performed on packed four single precision values, for each pair of the
corresponding data elements separately, the result is stored in the
destination register. When the mnemonic ends with \verb"ss", the source operand
can be a 32--bit memory location or a SSE register, the destination operand
must be a SSE register and the operation is performed on single precision
values, only low double words of SSE registers are used in this case, the
result is stored in the low double word of destination register. 

\index{addps}\index{addss}\index{subps}\index{subss}\index{mulps}\index{mulss}
\index{divps}\index{divss}\index{rcpps}\index{rcpss}\index{sqrtps}\index{sqrtss}
\index{rsqrtps}\index{rsqrtss}\index{maxps}\index{maxss}\index{minps}\index{minss}
\verb"addps" and \verb"addss" add the values, \verb"subps" and \verb"subss" substract the 
source value from destination value, \verb"mulps" and \verb"mulss" multiply the values, 
\verb"divps" and \verb"divss" divide the destination value by the source value, 
\verb"rcpps" and \verb"rcpss" compute the approximate reciprocal of the source value, 
\verb"sqrtps" and \verb"sqrtss" compute the square root of the source value, 
\verb"rsqrtps" and \verb"rsqrtss" compute the approximate reciprocal of square root 
of the source value, \verb"maxps" and \verb"maxss" compare the source and destination 
values and return the greater one, \verb"minps" and \verb"minss" compare the source and 
destination values and return the lesser one.
\begin{verbatim}
    mulss xmm0,[ebx]   ; multiply single precision values
    addps xmm3,xmm7    ; add packed single precision values
\end{verbatim}

\index{andps}\index{andnps}\index{orps}\index{xorps}
\verb"andps", \verb"andnps", \verb"orps" and \verb"xorps" perform the logical operations on
packed single precision values. The source operand can be a 128--bit memory
location or a SSE register, the destination operand must be a SSE register.

\index{cmpps}\index{cmpss}\index{cmpeqps}\index{cmpeqss}\index{cmpltps}\index{cmpltss}
\index{cmpleps}\index{cmpless}\index{cmpunordps}\index{cmpunordss}\index{cmpneqps}\index{cmpneqss}
\index{cmpnltps}\index{cmpnltss}\index{cmpnleps}\index{cmpnless}\index{cmpordps}\index{cmpordss}
\verb"cmpps" compares packed single precision values and returns a mask result
into the destination operand, which must be a SSE register. The source operand
can be a 128--bit memory location or SSE register, the third operand must be an
immediate operand selecting code of one of the eight compare conditions
(table \ref{tab:SSE_conditions}). \verb"cmpss" performs the same operation on single precision values,
only low double word of destination register is affected, in this case source
operand can be a 32--bit memory location or SSE register. These two
instructions have also variants with only two operands and the condition
encoded within mnemonic. Their mnemonics are obtained by attaching the
mnemonic from table \ref{tab:SSE_conditions} to the \verb"cmp" mnemonic and then attaching the \verb"ps" or
\verb"ss" at the end.
\begin{verbatim}
    cmpps xmm2,xmm4,0  ; compare packed single precision values
    cmpltss xmm0,[ebx] ; compare single precision values
\end{verbatim}

\begin{table}[hbt]
\begin{center}\begin{tabular}{|c|c|c|}
\hline
Code & Mnemonic & Description \\
\hline \hline
0 & \verb"eq" & equal \\
\hline
1 & \verb"lt" & less than \\
\hline
2 & \verb"le" & less than or equal \\
\hline
3 & \verb"unord" & unordered \\
\hline
4 & \verb"neq" & not equal \\
\hline
5 & \verb"nlt" & not less than \\
\hline
6 & \verb"nle" & not less than nor equal \\
\hline
7 & \verb"ord" & ordered \\
\hline
\end{tabular}\end{center}
\caption{SSE conditions.}
\label{tab:SSE_conditions}
\end{table}

\index{comiss}\index{ucomiss}
\verb"comiss" and \verb"ucomiss" compare the single precision values and set the ZF,
PF and CF flags to show the result. The destination operand must be a SSE
register, the source operand can be a 32--bit memory location or SSE register.

\index{shufps}
\verb"shufps" moves any two of the four single precision values from the
destination operand into the low quad word of the destination operand, and any
two of the four values from the source operand into the high quad word of the
destination operand. The destination operand must be a SSE register, the
source operand can be a 128--bit memory location or SSE register, the third
operand must be an 8--bit immediate value selecting which values will be moved
into the destination operand. Bits 0 and 1 select the value to be moved from
destination operand to the low double word of the result, bits 2 and 3 select
the value to be moved from the destination operand to the second double word,
bits 4 and 5 select the value to be moved from the source operand to the third
double word, and bits 6 and 7 select the value to be moved from the source
operand to the high double word of the result.
\begin{verbatim}
    shufps xmm0,xmm0,10010011b ; shuffle double words
\end{verbatim}

\index{unpckhps}\index{unpcklps}
\verb"unpckhps" performs an interleaved unpack of the values from the high parts
of the source and destination operands and stores the result in the
destination operand, which must be a SSE register. The source operand can be
a 128--bit memory location or a SSE register. \verb"unpcklps" performs an
interleaved unpack of the values from the low parts of the source and
destination operand and stores the result in the destination operand,
the rules for operands are the same.

\index{cvtpi2ps}
\verb"cvtpi2ps" converts packed two double word integers into the the packed two
single precision floating point values and stores the result in the low quad
word of the destination operand, which should be a SSE register. The source
operand can be a 64--bit memory location or MMX register.
\begin{verbatim}
    cvtpi2ps xmm0,mm0  ; integers to single precision values
\end{verbatim}

\index{cvtsi2ss}
\verb"cvtsi2ss" converts a double word integer into a single precision floating
point value and stores the result in the low double word of the destination
operand, which should be a SSE register. The source operand can be a 32--bit
memory location or 32--bit general register.
\begin{verbatim}
    cvtsi2ss xmm0,eax  ; integer to single precision value
\end{verbatim}

\index{cvtps2pi}\index{cvttps2pi}
\verb"cvtps2pi" converts packed two single precision floating point values into
packed two double word integers and stores the result in the destination
operand, which should be a MMX register. The source operand can be a 64--bit
memory location or SSE register, only low quad word of SSE register is used.
\verb"cvttps2pi" performs the similar operation, except that truncation is used to
round a source values to integers, rules for the operands are the same.
\begin{verbatim}
    cvtps2pi mm0,xmm0  ; single precision values to integers
\end{verbatim}

\index{cvtss2si}\index{cvttss2si}
\verb"cvtss2si" convert a single precision floating point value into a double
word integer and stores the result in the destination operand, which should be
a 32--bit general register. The source operand can be a 32--bit memory location
or SSE register, only low double word of SSE register is used. \verb"cvttss2si"
performs the similar operation, except that truncation is used to round a
source value to integer, rules for the operands are the same.
\begin{verbatim}
    cvtss2si eax,xmm0  ; single precision value to integer
\end{verbatim}

\index{pextrw}
\verb"pextrw" copies the word in the source operand specified by the third
operand to the destination operand. The source operand must be a MMX register,
the destination operand must be a 32--bit general register (the high word of
the destination is cleared), the third operand must an 8--bit immediate value.
\begin{verbatim}
    pextrw eax,mm0,1   ; extract word into eax
\end{verbatim}

\index{pinsrw}
\verb"pinsrw" inserts a word from the source operand in the destination operand
at the location specified with the third operand, which must be an 8--bit
immediate value. The destination operand must be a MMX register, the source
operand can be a 16--bit memory location or 32--bit general register (only low
word of the register is used).
\begin{verbatim}
    pinsrw mm1,ebx,2   ; insert word from ebx
\end{verbatim}

\index{pavgb}\index{pavgw}\index{pmaxub}\index{pminub}\index{pmaxsw}\index{pminsw}
\index{pmulhuw}\index{psadbw}
\verb"pavgb" and \verb"pavgw" compute average of packed bytes or words. \verb"pmaxub"
return the maximum values of packed unsigned bytes, \verb"pminub" returns the
minimum values of packed unsigned bytes, \verb"pmaxsw" returns the maximum values
of packed signed words, \verb"pminsw" returns the minimum values of packed signed
words. \verb"pmulhuw" performs a unsigned multiplication of the packed words and stores
the high words of the results in the destination operand. \verb"psadbw" computes
the absolute differences of packed unsigned bytes, sums the differences, and
stores the sum in the low word of destination operand. All these instructions
follow the same rules for operands as the general MMX operations described in
previous section.

\index{pmovmskb}
\verb"pmovmskb" creates a mask made of the most significant bit of each byte in
the source operand and stores the result in the low byte of destination
operand. The source operand must be a MMX register, the destination operand
must a 32--bit general register.

\index{pshufw}
\verb"pshufw" inserts words from the source operand in the destination operand
from the locations specified with the third operand. The destination operand
must be a MMX register, the source operand can be a 64--bit memory location or
MMX register, third operand must an 8--bit immediate value selecting which
values will be moved into destination operand, in the similar way as the third
operand of the \verb"shufps" instruction.

\index{movntq}\index{movntps}\index{maskmovq}
\verb"movntq" moves the quad word from the source operand to memory using a
non--temporal hint to minimize cache pollution. The source operand should be a
MMX register, the destination operand should be a 64--bit memory location.
\verb"movntps" stores packed single precision values from the SSE register to
memory using a non--temporal hint. The source operand should be a SSE register,
the destination operand should be a 128--bit memory location. \verb"maskmovq" stores
selected bytes from the first operand into a 64--bit memory location using a
non--temporal hint. Both operands should be a MMX registers, the second operand
selects wich bytes from the source operand are written to memory. The
memory location is pointed by DI (or EDI) register in the segment selected
by DS.

\index{prefetch0}\index{prefetch1}\index{prefetch2}\index{prefetchnta}
\verb"prefetcht0", \verb"prefetcht1", \verb"prefetcht2" and \verb"prefetchnta" fetch the line
of data from memory that contains byte specified with the operand to a
specified location in hierarchy.  The operand should be an 8--bit memory
location.

\index{sfence}
\verb"sfence" performs a serializing operation on all instruction storing to
memory that were issued prior to it. This instruction has no operands.

\index{ldmxcsr}\index{stmxcsr}
\verb"ldmxcsr" loads the 32--bit memory operand into the MXCSR register. \verb"stmxcsr"
stores the contents of MXCSR into a 32--bit memory operand.

\index{fxsave}\index{fxrstor}\index{fxsave}
\verb"fxsave" saves the current state of the FPU, MXCSR register, and all the FPU
and SSE registers to a 512--byte memory location specified in the destination
operand. \verb"fxrstor" reloads data previously stored with \verb"fxsave" instruction
from the specified 512--byte memory location. The memory operand for both those
instructions must be aligned on 16 byte boundary, it should declare operand
of no specified size.

\subsection{SSE2 instructions}
The SSE2 extension introduces the operations on packed double precision
floating point values, extends the syntax of MMX instructions, and adds also
some new instructions.

\index{movapd}\index{movupd}
\verb"movapd" and \verb"movupd" transfer a double quad word operand containing packed
double precision values from source operand to destination operand. These
instructions are analogous to \verb"movaps" and \verb"movups" and have the same rules
for operands.

\index{movlpd}\index{movhpd}
\verb"movlpd" moves double precision value between the memory and the low quad
word of SSE register. \verb"movhpd" moved double precision value between the memory
and the high quad word of SSE register. These instructions are analogous to
\verb"movlps" and \verb"movhps" and have the same rules for operands.

\index{movmskpd}
\verb"movmskpd" transfers the most significant bit of each of the two double
precision values in the SSE register into low two bits of a general register.
This instruction is analogous to \verb"movmskps" and has the same rules for
operands.

\index{movsd}
\verb"movsd" transfers a double precision value between source and destination
operand (only the low quad word is trasferred). At least one of the operands
have to be a SSE register, the second one can be also a SSE register or 64--bit
memory location.

\index{addpd}\index{addsd}\index{subpd}\index{subsd}\index{mulpd}\index{mulsd}
\index{divpd}\index{divsd}\index{sqrtpd}\index{sqrtsd}\index{maxpd}\index{maxsd}
\index{minpd}\index{minsd}
Arithmetic operations on double precision values are: \verb"addpd", \verb"addsd",
\verb"subpd", \verb"subsd", \verb"mulpd", \verb"mulsd", \verb"divpd", \verb"divsd", \verb"sqrtpd", \verb"sqrtsd",
\verb"maxpd", \verb"maxsd", \verb"minpd", \verb"minsd", and they are analoguous to arithmetic
operations on single precision values described in previous section. When the
mnemonic ends with \verb"pd" instead of \verb"ps", the operation is performed on packed
two double precision values, but rules for operands are the same. When the
mnemonic ends with \verb"sd" instead of \verb"ss", the source operand can be a 64--bit
memory location or a SSE register, the destination operand must be a SSE
register and the operation is performed on double precision values, only low
quad words of SSE registers are used in this case.

\index{andpd}\index{andnpd}\index{orpd}\index{xorpd}
\verb"andpd", \verb"andnpd", \verb"orpd" and \verb"xorpd" perform the logical operations on
packed double precision values. They are analoguous to SSE logical operations
on single prevision values and have the same rules for operands.

\index{cmppd}\index{cmpsd}\index{cmpeqpd}\index{cmpeqsd}\index{cmpltpd}\index{cmpltsd}
\index{cmplepd}\index{cmplesd}\index{cmpunordpd}\index{cmpunordsd}\index{cmpneqpd}\index{cmpneqsd}
\index{cmpnltpd}\index{cmpnltsd}\index{cmpnlepd}\index{cmpnlesd}\index{cmpordpd}\index{cmpordsd}
\verb"cmppd" compares packed double precision values and returns and returns a
mask result into the destination operand. This instruction is analoguous to
\verb"cmpps" and has the same rules for operands. \verb"cmpsd" performs the same
operation on double precision values, only low quad word of destination
register is affected, in this case source operand can be a 64--bit memory or
SSE register. Variant with only two operands are obtained by attaching the
condition mnemonic from table \ref{tab:SSE_conditions} to the \verb"cmp" mnemonic and then attaching
the \verb"pd" or \verb"sd" at the end.

\index{comisd}\index{ucomisd}
\verb"comisd" and \verb"ucomisd" compare the double precision values and set the ZF,
PF and CF flags to show the result. The destination operand must be a SSE
register, the source operand can be a 128--bit memory location or SSE register.

\index{shufpd}\index{shufps}
\verb"shufpd" moves any of the two double precision values from the destination
operand into the low quad word of the destination operand, and any of the two
values from the source operand into the high quad word of the destination
operand. This instruction is analoguous to \verb"shufps" and has the same rules for
operand. Bit 0 of the third operand selects the value to be moved from the
destination operand, bit 1 selects the value to be moved from the source
operand, the rest of bits are reserved and must be zeroed.

\index{unpckhpd}\index{unpcklpd}
\verb"unpckhpd" performs an unpack of the high quad words from the source and
destination operands, \verb"unpcklpd" performs an unpack of the low quad words from
the source and destination operands. They are analoguous to \verb"unpckhps" and
\verb"unpcklps", and have the same rules for operands.

\index{cvtps2pd}\index{cvtpd2ps}\index{cvtss2sd}\index{cvtsd2ss}
\verb"cvtps2pd" converts the packed two single precision floating point values to
two packed double precision floating point values, the destination operand
must be a SSE register, the source operand can be a 64--bit memory location or
SSE register. \verb"cvtpd2ps" converts the packed two double precision floating
point values to packed two single precision floating point values, the
destination operand must be a SSE register, the source operand can be a
128--bit memory location or SSE register. \verb"cvtss2sd" converts the single
precision floating point value to double precision floating point value, the
destination operand must be a SSE register, the source operand can be a 32--bit
memory location or SSE register. \verb"cvtsd2ss" converts the double precision
floating point value to single precision floating point value, the destination
operand must be a SSE register, the source operand can be 64--bit memory
location or SSE register.

\index{cvtpi2pd}\index{cvtsi2sd}\index{cvtpd2pi}
\index{cvttpd2pi}\index{cvtsd2si}\index{cvttsd2si}
\verb"cvtpi2pd" converts packed two double word integers into the the packed
double precision floating point values, the destination operand must be a SSE
register, the source operand can be a 64--bit memory location or MMX register.
\verb"cvtsi2sd" converts a double word integer into a double precision floating
point value, the destination operand must be a SSE register, the source
operand can be a 32--bit memory location or 32--bit general register. \verb"cvtpd2pi"
converts packed double precision floating point values into packed two double
word integers, the destination operand should be a MMX register, the source
operand can be a 128--bit memory location or SSE register. \verb"cvttpd2pi" performs
the similar operation, except that truncation is used to round a source values
to integers, rules for operands are the same. \verb"cvtsd2si" converts a double
precision floating point value into a double word integer, the destination
operand should be a 32--bit general register, the source operand can be a
64--bit memory location or SSE register. \verb"cvttsd2si" performs the similar
operation, except that truncation is used to round a source value to integer,
rules for operands are the same.

\index{cvtps2dq}\index{cvttps2dq}
\index{cvtpd2dq}\index{cvttpd2dq}\index{cvtdq2ps}
\verb"cvtps2dq" and \verb"cvttps2dq" convert packed single precision floating point
values to packed four double word integers, storing them in the destination
operand. \verb"cvtpd2dq" and \verb"cvttpd2dq" convert packed double precision floating
point values to packed two double word integers, storing the result in the low
quad word of the destination operand. \verb"cvtdq2ps" converts packed four double 
word integers to packed single precision floating point values. 

For all these instruction destination operand must be a SSE register, the
source operand can be a 128--bit memory location or SSE register.

\index{cvtdq2pd}
\verb"cvtdq2pd" converts packed two double word integers from the low quad word
of the source operand to packed double precision floating point values, the source can be a 64-bit
memory location or SSE register, destination has to be SSE register.

\index{movdqa}\index{movdqu}
\verb"movdqa" and \verb"movdqu" transfer a double quad word operand containing packed
integers from source operand to destination operand. At least one of the
operands have to be a SSE register, the second one can be also a SSE register
or 128--bit memory location. Memory operands for \verb"movdqa" instruction must be
aligned on boundary of 16 bytes, operands for \verb"movdqu" instruction don't have
to be aligned.

\index{movq2dq}\index{movdq2q}
\verb"movq2dq" moves the contents of the MMX source register to the low quad word
of destination SSE register. \verb"movdq2q" moves the low quad word from the source
SSE register to the destination MMX register.
\begin{verbatim}
    movq2dq xmm0,mm1   ; move from MMX register to SSE register
    movdq2q mm0,xmm1   ; move from SSE register to MMX register
\end{verbatim}

\index{pshufhw}\index{pshuflw}\index{pshufd}
All MMX instructions operating on the 64--bit packed integers (those with
mnemonics starting with \verb"p") are extended to operate on 128--bit packed
integers located in SSE registers. Additional syntax for these instructions
needs an SSE register where MMX register was needed, and the 128--bit memory
location or SSE register where 64--bit memory location or MMX register were
needed. The exception is \verb"pshufw" instruction, which doesn't allow extended
syntax, but has two new variants: \verb"pshufhw" and \verb"pshuflw", which allow only
the extended syntax, and perform the same operation as \verb"pshufw" on the high
or low quad words of operands respectively. Also the new instruction \verb"pshufd"
is introduced, which performs the same operation as \verb"pshufw", but on the
double words instead of words, it allows only the extended syntax.
\begin{verbatim}
    psubb xmm0,[esi]   ; substract 16 packed bytes
    pextrw eax,xmm0,7  ; extract highest word into eax
\end{verbatim}

\index{paddq}\index{psubq}\index{pmuludq}
\verb"paddq" performs the addition of packed quad words, \verb"psubq" performs the
substraction of packed quad words, \verb"pmuludq" performs an unsigned multiplication
of low double words from each corresponding quad words and returns the results
in packed quad words. These instructions follow the same rules for operands as
the general MMX operations described in \ref{sec:MMX_instructions}.

\index{pslldq}\index{psrldq}
\verb"pslldq" and \verb"psrldq" perform logical shift left or right of the double
quad word in the destination operand by the amount of bytes specified in the source
operand. The destination operand should be a SSE register, source operand
should be an 8--bit immediate value.

\index{punpckhqdq}\index{punpcklqdq}
\verb"punpckhqdq" interleaves the high quad word of the source operand and the
high quad word of the destination operand and writes them to the destination
SSE register. \verb"punpcklqdq" interleaves the low quad word of the source operand
and the low quad word of the destination operand and writes them to the
destination SSE register. The source operand can be a 128--bit memory location
or SSE register.

\index{movntdq}\index{movntpd}\index{movnti}\index{maskmovdqu}
\verb"movntdq" stores packed integer data from the SSE register to memory using
non--temporal hint. The source operand should be a SSE register, the
destination operand should be a 128--bit memory location. \verb"movntpd" stores
packed double precision values from the SSE register to memory using a
non--temporal hint. Rules for operand are the same. \verb"movnti" stores integer
from a general register to memory using a non--temporal hint. The source
operand should be a 32--bit general register, the destination operand should
be a 32--bit memory location. \verb"maskmovdqu" stores selected bytes from the first
operand into a 128--bit memory location using a non--temporal hint. Both
operands should be a SSE registers, the second operand selects wich bytes from
the source operand are written to memory. The memory location is pointed by DI
(or EDI) register in the segment selected by DS and does not need to be
aligned.

\index{clflush}
\verb"clflush" writes and invalidates the cache line associated with the address
of byte specified with the operand, which should be a 8--bit memory location.

\index{lfence}\index{mfence}\index{sfence}\index{lfence}
\verb"lfence" performs a serializing operation on all instruction loading from
memory that were issued prior to it. \verb"mfence" performs a serializing operation
on all instruction accesing memory that were issued prior to it, and so it
combines the functions of \verb"sfence" (described in previous section) and
\verb"lfence" instructions. These instructions have no operands.

\subsection{SSE3 instructions}
Prescott technology introduced some new instructions to improve
the performance of SSE and SSE2 -- this extension is called SSE3.

\index{fisttp}
\verb"fisttp" behaves like the \verb"fistp" instruction and accepts the same operands,
the only difference is that it always used truncation, irrespective of the
rounding mode.

\index{movshdup}
\verb"movshdup" loads into destination operand the 128--bit value obtained from
the source value of the same size by filling the each quad word with the two
duplicates of the value in its high double word.

\index{movsldup}
\verb"movsldup" performs the same action, except it duplicates the values of low double words.
The destination operand should be SSE register, the source operand can be SSE register or
128--bit memory location.

\index{movddup}
\verb"movddup" loads the 64--bit source value and duplicates it into high and low
quad word of the destination operand. The destination operand should be SSE
register, the source operand can be SSE register or 64--bit memory location.

\index{lddqu}
\verb"lddqu" is functionally equivalent to \verb"movdqu" with memory as
source operand, but it may improve performance when the source operand crosses
a cacheline boundary. The destination operand has to be SSE register, the source
operand must be 128--bit memory location.

\index{adddubps}
\verb"addsubps" performs single precision addition of second and fourth pairs and
single precision substracion of the first and third pairs of floating point
values in the operands.

\index{addsubpd}
\verb"addsubpd" performs double precision addition of the
second pair and double precision substraction of the first pair of floating
point values in the operand.

\index{haddps}
\verb"haddps" performs the addition of two single
precision values within the each quad word of source and destination operands,
and stores the results of such horizontal addition of values from destination
operand into low quad word of destination operand, and the results from the
source operand into high quad word of destination operand.

\index{haddpd}
\verb"haddpd" performs
the addition of two double precision values within each operand, and stores
the result from destination operand into low quad word of destination operand,
and the result from source operand into high quad word of destination operand.
All these instruction need the destination operand to be SSE register, source
operand can be SSE register or 128--bit memory location.

\index{monitor}
\verb"monitor" sets up an address range for monitoring of write--back stores. It
need its three operands to be EAX, ECX and EDX register in that order.

\index{mwait}
\verb"mwait" waits for a write--back store to the address range set up by the
\verb"monitor" instruction.
It uses two operands with additional parameters, first being the EAX and second
the ECX register.

The functionality of SSE3 is further extended by the set of Supplemental
SSE3 instructions (SSSE3). They generally follow the same rules for operands
as all the MMX operations extended by SSE.

\index{phaddw}\index{phaddd}\index{phaddsw}
\index{phsubw}\index{phsubd}\index{phsubsw}
\verb"phaddw" and \verb"phaddd" perform the horizontal additional of the pairs of
adjacent values from both the source and destination operand, and stores the
sums into the destination (sums from the source operand go into lower part of
destination register). They operate on 16--bit or 32--bit chunks, respectively.
\verb"phaddsw" performs the same operation on signed 16--bit packed values, but the
result of each addition is saturated. \verb"phsubw" and \verb"phsubd" analogously
perform the horizontal substraction of 16--bit or 32--bit packed value, and
\verb"phsubsw" performs the horizontal substraction of signed 16--bit packed values
with saturation.

\index{pabsb}\index{pabsw}\index{pabsd}
\verb"pabsb", \verb"pabsw" and \verb"pabsd" calculate the absolute value of each signed
packed signed value in source operand and stores them into the destination
register. They operator on 8--bit, 16--bit and 32--bit elements respectively.

\index{pmaddubsw}
\verb"pmaddubsw" multiplies signed 8--bit values from the source operand with the
corresponding unsigned 8--bit values from the destination operand to produce
intermediate 16--bit values, and every adjacent pair of those intermediate
values is then added horizontally and those 16--bit sums are stored into the
destination operand.

\index{pmulhrsw}
\verb"pmulhrsw" multiplies corresponding 16--bit integers from the source and
destination operand to produce intermediate 32--bit values, and the 16 bits
next to the highest bit of each of those values are then rounded and packed
into the destination operand.

\index{pshufb}
\verb"pshufb" shuffles the bytes in the destination operand according to the
mask provided by source operand - each of the bytes in source operand is
an index of the target position for the corresponding byte in the destination.

\index{psignb}\index{psignw}\index{psignd}
\verb"psignb", \verb"psignw" and \verb"psignd" perform the operation on 8--bit, 16--bit or
32--bit integers in destination operand, depending on the signs of the values
in the source. If the value in source is negative, the corresponding value in
the destination register is negated, if the value in source is positive, no
operation is performed on the corresponding value is performed, and if the
value in source is zero, the value in destination is zeroed, too.

\index{palifnr}
\verb"palignr" appends the source operand to the destination operand to form the
intermediate value of twice the size, and then extracts into the destination
register the 64 or 128 bits that are right-aligned to the byte offset
specified by the third operand, which should be an 8--bit immediate value. This
is the only SSSE3 instruction that takes three arguments.


\subsection{AMD 3DNow! instructions}
The 3DNow! extension adds a new MMX instructions to those described in \ref{sec:MMX_instructions},
and introduces operation on the 64--bit packed floating point values, each
consisting of two single precision floating point values.

These instructions follow the same rules as the general MMX operations, the
destination operand should be a MMX register, the source operand can be a MMX
register or 64--bit memory location. 

\index{pavgusb}\index{pmulhrw}\index{pi2fd}\index{pf2id}\index{pi2fw}\index{pf2iw}
\index{pfadd}\index{pfsub}\index{pfsubr}\index{pfmul}
\index{pfacc}\index{pfnacc}\index{pfpnacc}
\index{pfmax}\index{pfmin}\index{pswapd}\index{pfrcp}\index{pfrsqrt}
\index{pfrcpit1}\index{pfrsqit1}\index{pfrcpit2}
\index{pfcmpeq}\index{pfcmpge}\index{pfcmpgt}
\verb"pavgusb" computes the rounded averages
of packed unsigned bytes. \verb"pmulhrw" performs a signed multiplication of the packed
words, round the high word of each double word results and stores them in the
destination operand. \verb"pi2fd" converts packed double word integers into
packed floating point values. \verb"pf2id" converts packed floating point values
into packed double word integers using truncation. \verb"pi2fw" converts packed
word integers into packed floating point values, only low words of each
double word in source operand are used. \verb"pf2iw" converts packed floating
point values to packed word integers, results are extended to double words
using the sign extension. \verb"pfadd" adds packed floating point values. \verb"pfsub"
and \verb"pfsubr" substracts packed floating point values, the first one substracts
source values from destination values, the second one substracts destination
values from the source values. \verb"pfmul" multiplies packed floating point
values. \verb"pfacc" adds the low and high floating point values of the destination
operand, storing the result in the low double word of destination, and adds
the low and high floating point values of the source operand, storing the
result in the high double word of destination. \verb"pfnacc" substracts the high
floating point value of the destination operand from the low, storing the
result in the low double word of destination, and substracts the high floating
point value of the source operand from the low, storing the result in the high
double word of destination. \verb"pfpnacc" substracts the high floating point value
of the destination operand from the low, storing the result in the low double
word of destination, and adds the low and high floating point values of the
source operand, storing the result in the high double word of destination.
\verb"pfmax" and \verb"pfmin" compute the maximum and minimum of floating point values.
\verb"pswapd" reverses the high and low double word of the source operand. \verb"pfrcp"
returns an estimates of the reciprocals of floating point values from the
source operand, \verb"pfrsqrt" returns an estimates of the reciprocal square
roots of floating point values from the source operand, \verb"pfrcpit1" performs
the first step in the Newton--Raphson iteration to refine the reciprocal
approximation produced by \verb"pfrcp" instruction, \verb"pfrsqit1" performs the first
step in the Newton--Raphson iteration to refine the reciprocal square root
approximation produced by \verb"pfrsqrt" instruction, \verb"pfrcpit2" performs the
second final step in the Newton--Raphson iteration to refine the reciprocal
approximation or the reciprocal square root approximation. \verb"pfcmpeq",
\verb"pfcmpge" and \verb"pfcmpgt" compare the packed floating point values and sets
all bits or zeroes all bits of the correspoding data element in the
destination operand according to the result of comparison, first checks
whether values are equal, second checks whether destination value is greater
or equal to source value, third checks whether destination value is greater
than source value.

\index{prefetch}\index{prefetchw}
\verb"prefetch" and \verb"prefetchw" load the line of data from memory that contains
byte specified with the operand into the data cache, \verb"prefetchw" instruction
should be used when the data in the cache line is expected to be modified,
otherwise the \verb"prefetch" instruction should be used. The operand should be an
8--bit memory location.

\index{femms}
\verb"femms" performs a fast clear of MMX state. It has no operands.

\subsection{The x86-64 long mode instructions}

The AMD64 and EM64T architectures (we will use the common name x86--64 for them
both) extend the x86 instruction set for the 64--bit processing. While legacy
and compatibility modes use the same set of registers and instructions, the
new long mode extends the x86 operations to 64 bits and introduces several new
registers. You can turn on generating the code for this mode with the \verb"use64"
directive.

Each of the general purpose registers is extended to 64 bits and the eight
whole new general purpose registers and also eight new SSE registers are added.
See table \ref{tab:x86_64_registers} for the summary of new registers (only the ones that was not
listed in table \ref{tab:registers}). The general purpose registers of smallers sizes are the
low order portions of the larger ones. You can still access the \verb"ah", \verb"bh",
\verb"ch" and \verb"dh" registers in long mode, but you cannot use them in the same
instruction with any of the new registers.

\begin{table}[htb]
\begin{center}\begin{tabular}{|c||c|c|c|c|c|c|}
\hline
Type & \multicolumn{4}{c|}{General} & SSE & AVX \\
\hline
Bits & 8 & 16 & 32 & 64 & 128 & 256 \\
\hline \hline
& & & & \verb"rax" & & \\
& & & & \verb"rcx" & & \\
& & & & \verb"rdx" & & \\
& & & & \verb"rbx" & & \\
& \verb"spl" & & & \verb"rsp" & & \\
& \verb"bpl" & & & \verb"rbp" & & \\
& \verb"sil" & & & \verb"rsi" & & \\
& \verb"dil" & & & \verb"rdi" & & \\
& \verb"r8b" & \verb"r8w" & \verb"r8d" & \verb"r8" & \verb"xmm8" & \verb"ymm8" \\
& \verb"r9b" & \verb"r9w" & \verb"r9d" & \verb"r9" & \verb"xmm9" & \verb"ymm9" \\
& \verb"r10b" & \verb"r10w" & \verb"r10d" & \verb"r10" & \verb"xmm10" & \verb"ymm10" \\
& \verb"r11b" & \verb"r11w" & \verb"r11d" & \verb"r11" & \verb"xmm11" & \verb"ymm11" \\
& \verb"r12b" & \verb"r12w" & \verb"r12d" & \verb"r12" & \verb"xmm12" & \verb"ymm12" \\
& \verb"r13b" & \verb"r13w" & \verb"r13d" & \verb"r13" & \verb"xmm13" & \verb"ymm13" \\
& \verb"r14b" & \verb"r14w" & \verb"r14d" & \verb"r14" & \verb"xmm14" & \verb"ymm14" \\
& \verb"r15b" & \verb"r15w" & \verb"r15d" & \verb"r15" & \verb"xmm15" & \verb"ymm15" \\
\hline
\end{tabular}\end{center}
\caption{New registers in long mode.} \label{tab:x86_64_registers}
\end{table}

In general any instruction from x86 architecture, which allowed 16--bit or
32--bit operand sizes, in long mode allows also the 64--bit operands. The 64--bit
registers should be used for addressing in long mode, the 32--bit addressing
is also allowed, but it's not possible to use the addresses based on 16--bit
registers. Below are the samples of new operations possible in long mode on the
example of \verb"mov" instruction:
\begin{verbatim}
    mov rax,r8   ; transfer 64-bit general register
    mov al,[rbx] ; transfer memory addressed by 64-bit register
\end{verbatim}
The long mode uses also the instruction pointer based addresses, you can
specify it manually with the special RIP register symbol, but such addressing
is also automatically generated by flat assembler, since there is no 64--bit
absolute addressing in long mode. You can still force the assembler to use the
32--bit absolute addressing by putting the \verb"dword" size override for address
inside the square brackets. There is also one exception, where the 64--bit
absolute addressing is possible, it's the \verb"mov" instruction with one of the
operand being accumulator register, and second being the memory operand.
To force the assembler to use the 64--bit absolute addressing there, use the
\verb"qword" size operator for address inside the square brackets. When no size
operator is applied to address, assembler generates the optimal form
automatically.
\begin{verbatim}
    mov [qword 0],rax  ; absolute 64-bit addressing
    mov [dword 0],r15d ; absolute 32-bit addressing
    mov [0],rsi        ; automatic RIP-relative addressing
    mov [rip+3],sil    ; manual RIP-relative addressing
\end{verbatim}

Also as the immediate operands for 64--bit operations only the signed 32--bit
values are possible, with the only exception being the \verb"mov" instruction with
destination operand being 64--bit general purpose register. Trying to force the
64--bit immediate with any other instruction will cause an error.

If any operation is performed on the 32--bit general registers in long mode,
the upper 32 bits of the 64--bit registers containing them are filled with
zeros. This is unlike the operations on 16--bit or 8--bit portions of those
registers, which preserve the upper bits.

\index{cdqe}\index{cqo}\index{movsxd}
Three new type conversion instructions are available. The \verb"cdqe" sign extends
the double word in EAX into quad word and stores the result in RAX register.
\verb"cqo" sign extends the quad word in RAX into double quad word and stores the
extra bits in the RDX register. These instructions have no operands.
\verb"movsxd" sign extends the double word source operand, being either the 32--bit register
or memory, into 64--bit destination operand, which has to be register.
No analogous instruction is needed for the zero extension, since it is done
automatically by any operations on 32--bit registers, as noted in previous
paragraph. And the \verb"movzx" and \verb"movsx" instructions, conforming to the general
rule, can be used with 64--bit destination operand, allowing extension of byte
or word values into quad words.

All the binary arithmetic and logical instruction have been promoted to allow
64--bit operands in long mode. The use of decimal arithmetic instructions in
long mode is prohibited.

The stack operations, like \verb"push" and \verb"pop" in long mode default to 64--bit
operands and it's not possible to use 32--bit operands with them.
The \verb"pusha" and \verb"popa" are disallowed in long mode.

The indirect near jumps and calls in long mode default to 64--bit operands and
it's not possible to use the 32--bit operands with them. On the other hand, the
indirect far jumps and calls allow any operands that were allowed by the x86
architecture and also 80--bit memory operand is allowed (though only EM64T seems
to implement such variant), with the first eight bytes defining the offset and
two last bytes specifying the selector. The direct far jumps and calls are not
allowed in long mode.

\index{movsq}\index{cmpsq}\index{scasq}\index{lodsq}\index{stosq}
The I/O instructions, \verb"in", \verb"out", \verb"ins" and \verb"outs" are the exceptional
instructions that are not extended to accept quad word operands in long mode.
But all other string operations are, and there are new short forms \verb"movsq",
\verb"cmpsq", \verb"scasq", \verb"lodsq" and \verb"stosq" introduced for the variants of string
operations for 64--bit string elements. The RSI and RDI registers are used by
default to address the string elements.

The \verb"lfs", \verb"lgs" and \verb"lss" instructions are extended to accept 80--bit source
memory operand with 64--bit destination register (though only EM64T seems to
implement such variant). The \verb"lds" and \verb"les" are disallowed in long mode.

The system instructions like \verb"lgdt" which required the 48--bit memory operand,
in long mode require the 80--bit memory operand.

\index{cmpxchg16b}
The \verb"cmpxchg16b" is the 64--bit equivalent of \verb"cmpxchg8b" instruction, it uses
the double quad word memory operand and 64--bit registers to perform the analoguous operation.

\index{fxsave64}\index{fxrstor64}
The \verb"fxsave64" and \verb"fxrstor64" are new variants of \verb"fxsave" and \verb"fxrstor"
instructions, available only in long mode, which use a different format of
storage area in order to store some pointers in full 64-bit size.

\index{swapgs}
\verb"swapgs" is the new instruction, which swaps the contents of GS register and
the KernelGSbase model--specific register (MSR address 0C0000102h).

\index{syscall}\index{sysret}\index{sysexitq}\index{sysretq}
\verb"syscall" and \verb"sysret" is the pair of new instructions that provide the
functionality similar to \verb"sysenter" and \verb"sysexit" in long mode, where the
latter pair is disallowed. The \verb"sysexitq" and \verb"sysretq" mnemonics provide the
64--bit versions of \verb"sysexit" and \verb"sysret" instructions.

\index{rdmsrq}\index{wrmsrq}
The \verb"rdmsrq" and \verb"wrmsrq" mnemonics are the 64--bit variants of the \verb"rdmsr"
and \verb"wrmsr" instructions.


\subsection{SSE4 instructions}

There are actually three different sets of instructions under the name SSE4.
Intel designed two of them, SSE4.1 and SSE4.2, with latter extending the
former into the full Intel's SSE4 set. On the other hand, the implementation
by AMD includes only a few instructions from this set, but also contains
some additional instructions, that are called the SSE4a set.

The SSE4.1 instructions mostly follow the same rules for operands, as
the basic SSE operations, so they require destination operand to be SSE
register and source operand to be 128--bit memory location or SSE register,
and some operations require a third operand, the 8--bit immediate value.

\index{pmulld}\index{pmuldq}\index{pminsb}\index{pmaxsb}\index{pminuw}
\index{pmaxuw}\index{pminud}\index{pmaxud}\index{pminsd}\index{pmaxsd}
\verb"pmulld" performs a signed multiplication of the packed double words and
stores the low double words of the results in the destination operand.
\verb"pmuldq" performs a two signed multiplications of the corresponding double
words in the lower quad words of operands, and stores the results as
packed quad words into the destination register. \verb"pminsb" and \verb"pmaxsb"
return the minimum or maximum values of packed signed bytes, \verb"pminuw" and
\verb"pmaxuw" return the minimum and maximum values of packed unsigned words,
\verb"pminud", \verb"pmaxud", \verb"pminsd" and \verb"pmaxsd" return minimum or maximum values
of packed unsigned or signed words. These instruction complement the
instructions computing packed minimum or maximum introduced by SSE.

\index{ptest}\index{pcmpeqq}
\verb"ptest" sets the ZF flag to one when the result of bitwise AND of the
both operands is zero, and zeroes the ZF otherwise. It also sets CF flag
to one, when the result of bitwise AND of the destination operand with
the bitwise NOT of the source operand is zero, and zeroes the CF otherwise.
\verb"pcmpeqq" compares packed quad words for equality, and fills the
corresponding elements of destination operand with either ones or zeros,
depending on the result of comparison.

\index{packusdw}
\verb"packusdw" converts packed signed double words from both the source and
destination operand into the unsigned words using saturation, and stores
the eight resulting word values into the destination register.

\index{phminposuw}
\verb"phminposuw" finds the minimum unsigned word value in source operand
and places it into the lowest word of destination operand, setting the
remaining upper bits of destination to zero.

\index{roundps}\index{roundss}\index{roundpd}\index{roundsd}
\verb"roundps", \verb"roundss", \verb"roundpd" and \verb"roundsd" perform the rounding of
packed or individual floating point value of single or double precision,
using the rounding mode specified by the third operand.
\begin{verbatim}
    roundsd xmm0,xmm1,0011b ; round toward zero
\end{verbatim}

\index{dpps}\index{dppd}\index{mpsadbw}\index{roundps}
\verb"dpps" calculates dot product of packed single precision floating point
values, that is it multiplies the corresponding pairs of values from source and
destination operand and then sums the products up. The high four bits of the
8--bit immediate third operand control which products are calculated and taken
to the sum, and the low four bits control, into which elements of destination
the resulting dot product is copied (the other elements are filled with zero).
\verb"dppd" calculates dot product of packed double precision floating point values.
The bits 4 and 5 of third operand control, which products are calculated and
added, and bits 0 and 1 of this value control, which elements in destination
register should get filled with the result. \verb"mpsadbw" calculates multiple sums
of absolute differences of unsigned bytes. The third operand controls, with
value in bits 0--1, which of the four-byte blocks in source operand is taken to
calculate the absolute differencies, and with value in bit 2, at which of the
two first four-byte block in destination operand start calculating multiple
sums. The sum is calculated from four absolute differencies between the
corresponding unsigned bytes in the source and destination block, and each next
sum is calculated in the same way, but taking the four bytes from destination
at the position one byte after the position of previous block. The four bytes
from the source stay the same each time. This way eight sums of absolute
differencies are calculated and stored as packed word values into the
destination operand. The instructions described in this paragraph follow the
same rules for operands, as \verb"roundps" instruction.

\index{blendps}\index{blendvps}\index{blendpd}\index{blendvpd}
\verb"blendps", \verb"blendvps", \verb"blendpd" and \verb"blendvpd" conditionally copy the
values from source operand into the destination operand, depending on the bits
of the mask provided by third operand. If a mask bit is set, the corresponding
element of source is copied into the same place in destination, otherwise this
position is destination is left unchanged. The rules for the first two operands
are the same, as for general SSE instructions. \verb"blendps" and \verb"blendpd" need
third operand to be 8--bit immediate, and they operate on single or double
precision values, respectively. \verb"blendvps" and \verb"blendvpd" require third operand
to be the XMM0 register.
\begin{verbatim}
    blendvps xmm3,xmm7,xmm0 ; blend according to mask
\end{verbatim}

\index{pblendw}\index{pblendvb}
\verb"pblendw" conditionally copies word elements from the source operand into the
destination, depending on the bits of mask provided by third operand, which
needs to be 8--bit immediate value. \verb"pblendvb" conditionally copies byte
elements from the source operands into destination, depending on mask defined
by the third operand, which has to be XMM0 register. These instructions follow
the same rules for operands as \verb"blendps" and \verb"blendvps" instructions,
respectively.

\index{insertps}
\verb"insertps" inserts a single precision floating point value taken from the
position in source operand specified by bits 6--7 of third operand into location
in destination register selected by bits 4--5 of third operand. Additionally,
the low four bits of third operand control, which elements in destination
register will be set to zero. The first two operands follow the same rules as
for the general SSE operation, the third operand should be 8--bit immediate.

\index{extractps}
\verb"extractps" extracts a single precision floating point value taken from the
location in source operand specified by low two bits of third operand, and
stores it into the destination operand. The destination can be a 32--bit memory
value or general purpose register, the source operand must be SSE register,
and the third operand should be 8--bit immediate value.
\begin{verbatim}
    extractps edx,xmm3,3 ; extract the highest value
\end{verbatim}

\index{pinsrb}\index{pinsrd}\index{pinsrq}
\verb"pinsrb", \verb"pinsrd" and \verb"pinsrq" copy a byte, double word or quad word from
the source operand into the location of destination operand determined by the
third operand. The destination operand has to be SSE register, the source
operand can be a memory location of appropriate size, or the 32--bit general
purpose register (but 64--bit general purpose register for \verb"pinsrq", which is
only available in long mode), and the third operand has to be 8--bit immediate
value. These instructions complement the \verb"pinsrw" instruction operating on SSE
register destination, which was introduced by SSE2.
\begin{verbatim}
    pinsrd xmm4,eax,1 ; insert double word into second position
\end{verbatim}

\index{pextrb}\index{pextrw}\index{pextrd}\index{pextrq}
\verb"pextrb", \verb"pextrw", \verb"pextrd" and \verb"pextrq" copy a byte, word, double word or
quad word from the location in source operand specified by third operand, into
the destination. The source operand should be SSE register, the third operand
should be 8--bit immediate, and the destination operand can be memory location
of appropriate size, or the 32--bit general purpose register (but 64--bit general
purpose register for \verb"pextrq", which is only available in long mode). The
\verb"pextrw" instruction with SSE register as source was already introduced by
SSE2, but SSE4 extends it to allow memory operand as destination.
\begin{verbatim}
    pextrw [ebx],xmm3,7 ; extract highest word into memory
\end{verbatim}

\index{pmovsxbw}\index{pmovzxbw}\index{pmovsxbd}\index{pmovzxbd}
\index{pmovsxbq}\index{pmovzxbq}\index{pmovsxwd}\index{pmovzxwd}
\index{pmovsxwq}\index{pmovzxwq}\index{pmovsxdq}\index{pmovzxdq}
\verb"pmovsxbw" and \verb"pmovzxbw" perform sign extension or zero extension of eight
byte values from the source operand into packed word values in destination
operand, which has to be SSE register. The source can be 64--bit memory or SSE
register - when it is register, only its low portion is used. \verb"pmovsxbd" and
\verb"pmovzxbd" perform sign extension or zero extension of the four byte values
from the source operand into packed double word values in destination operand,
the source can be 32--bit memory or SSE register. \verb"pmovsxbq" and \verb"pmovzxbq"
perform sign extension or zero extension of the two byte values from the
source operand into packed quad word values in destination operand, the source
can be 16--bit memory or SSE register. \verb"pmovsxwd" and \verb"pmovzxwd" perform sign
extension or zero extension of the four word values from the source operand
into packed double words in destination operand, the source can be 64--bit
memory or SSE register. \verb"pmovsxwq" and \verb"pmovzxwq" perform sign extension or
zero extension of the two word values from the source operand into packed quad
words in destination operand, the source can be 32--bit memory or SSE register.
\verb"pmovsxdq" and \verb"pmovzxdq" perform sign extension or zero extension of the two
double word values from the source operand into packed quad words in
destination operand, the source can be 64--bit memory or SSE register.
\begin{verbatim}
    pmovzxbq xmm0,word [si]  ; zero-extend bytes to quad words
    pmovsxwq xmm0,xmm1       ; sign-extend words to quad words
\end{verbatim}

\index{movntdqa}
\verb"movntdqa" loads double quad word from the source operand to the destination
using a non-temporal hint. The destination operand should be SSE register,
and the source operand should be 128--bit memory location.

The SSE4.2, described below, adds not only some new operations on SSE
registers, but also introduces some completely new instructions operating on
general purpose registers only.

\index{pcmpistri}\index{pcmpistrm}\index{pcmpestri}\index{pcmpestrm}
\verb"pcmpistri" compares two zero-ended (implicit length) strings provided in
its source and destination operand and generates an index stored to ECX;
\verb"pcmpistrm" performs the same comparison and generates a mask stored to XMM0.
\verb"pcmpestri" compares two strings of explicit lengths, with length provided
in EAX for the destination operand and in EDX for the source operand, and
generates an index stored to ECX; \verb"pcmpestrm" performs the same comparision
and generates a mask stored to XMM0. The source and destination operand follow
the same rules as for general SSE instructions, the third operand should be
8--bit immediate value determining the details of performed operation - refer to
Intel documentation for information on those details.

\index{pcmpgtq}
\verb"pcmpgtq" compares packed quad words, and fills the corresponding elements of
destination operand with either ones or zeros, depending on whether the value
in destination is greater than the one in source, or not. This instruction
follows the same rules for operands as \verb"pcmpeqq".

\index{crc32}
\verb"crc32" accumulates a CRC32 value for the source operand starting with
initial value provided by destination operand, and stores the result in
destination. Unless in long mode, the destination operand should be a 32--bit
general purpose register, and the source operand can be a byte, word, or double
word register or memory location. In long mode the destination operand can
also be a 64--bit general purpose register, and the source operand in such case
can be a byte or quad word register or memory location.
\begin{verbatim}
    crc32 eax,dl          ; accumulate CRC32 on byte value
    crc32 eax,word [ebx]  ; accumulate CRC32 on word value
    crc32 rax,qword [rbx] ; accumulate CRC32 on quad word value
\end{verbatim}

\index{popcnt}
\verb"popcnt" calculates the number of bits set in the source operand, which can
be 16--bit, 32--bit, or 64--bit general purpose register or memory location,
and stores this count in the destination operand, which has to be register of
the same size as source operand. The 64--bit variant is available only in long
mode.
\begin{verbatim}
    popcnt ecx,eax        ; count bits set to 1
\end{verbatim}

\index{lzcnt}
The SSE4a extension, which also includes the \verb"popcnt" instruction introduced
by SSE4.2, at the same time adds the \verb"lzcnt" instruction, which follows the
same syntax, and calculates the count of leading zero bits in source operand
(if the source operand is all zero bits, the total number of bits in source
operand is stored in destination).

\index{extrq}
\verb"extrq" extract the sequence of bits from the low quad word of SSE register
provided as first operand and stores them at the low end of this register,
filling the remaining bits in the low quad word with zeros. The position of bit
string and its length can either be provided with two 8--bit immediate values
as second and third operand, or by SSE register as second operand (and there
is no third operand in such case), which should contain position value in bits
8--13 and length of bit string in bits 0--5.
\begin{verbatim}
    extrq xmm0,8,7        ; extract 8 bits from position 7
    extrq xmm0,xmm5       ; extract bits defined by register
\end{verbatim}

\index{insertq}
\verb"insertq" writes the sequence of bits from the low quad word of the source
operand into specified position in low quad word of the destination operand,
leaving the other bits in low quad word of destination intact. The position
where bits should be written and the length of bit string can either be
provided with two 8--bit immediate values as third and fourth operand, or by
the bit fields in source operand (and there are only two operands in such
case), which should contain position value in bits 72--77 and length of bit
string in bits 64--69.
\begin{verbatim}
    insertq xmm1,xmm0,4,2 ; insert 4 bits at position 2
    insertq xmm1,xmm0     ; insert bits defined by register
\end{verbatim}

\index{movntss}\index{movntsd}
\verb"movntss" and \verb"movntsd" store single or double precision floating point
value from the source SSE register into 32--bit or 64--bit destination memory
location respectively, using non--temporal hint.

\subsection{AVX instructions}

The Advanced Vector Extensions introduce instructions that are new variants
of SSE instructions, with new scheme of encoding that allows extended syntax
having a destination operand separate from all the source operands. It also
introduces 256--bit AVX registers, which extend up the old 128--bit SSE
registers. Any AVX instruction that puts some result into SSE register, puts
zero bits into high portion of the AVX register containing it.

The AVX version of SSE instruction has the mnemonic obtained by prepending
SSE instruction name with \verb"v". For any SSE arithmetic instruction which had a
destination operand also being used as one of the source values, the AVX
variant has a new syntax with three operands -- the destination and two sources.
The destination and first source can be SSE registers, and second source can be
SSE register or memory. If the operation is performed on single pair of values,
the remaining bits of first source SSE register are copied into the the
destination register.
\begin{verbatim}
    vsubss xmm0,xmm2,xmm3         ; substract two 32-bit floats
    vmulsd xmm0,xmm7,qword [esi]  ; multiply two 64-bit floats
\end{verbatim}
In case of packed operations, each instruction can also operate on the 256--bit
data size when the AVX registers are specified instead of SSE registers, and
the size of memory operand is also doubled then.
\begin{verbatim}
    vaddps ymm1,ymm5,yword [esi]  ; eight sums of 32-bit float pairs
\end{verbatim}
The instructions that operate on packed integer types (in particular the ones
that earlier had been promoted from MMX to SSE) also acquired the new syntax
with three operands, however they are only allowed to operate on 128--bit
packed types and thus cannot use the whole AVX registers.
\begin{verbatim}
    vpavgw xmm3,xmm0,xmm2         ; average of 16-bit integers
    vpslld xmm1,xmm0,1            ; shift double words left
\end{verbatim}
If the SSE version of instruction had a syntax with three operands, the third
one being an immediate value, the AVX version of such instruction takes four
operands, with immediate remaining the last one.
\begin{verbatim}
    vshufpd ymm0,ymm1,ymm2,10010011b ; shuffle 64-bit floats
    vpalignr xmm0,xmm4,xmm2,3        ; extract byte aligned value
\end{verbatim}
The promotion to new syntax according to the rules described above has been
applied to all the instructions from SSE extensions up to SSE4, with the
exceptions described below.

\index{vdppd}
\verb"vdppd" instruction has syntax extended to four operans, but it does not
have a 256--bit version.

\index{vsqrtpd}\index{vsqrtps}\index{vrcpps}\index{vrsqrtps}
The are a few instructions, namely \verb"vsqrtpd", \verb"vsqrtps", \verb"vrcpps" and
\verb"vrsqrtps", which can operate on 256--bit data size, but retained the syntax
with only two operands, because they use data from only one source:
\begin{verbatim}
    vsqrtpd ymm1,ymm0         ; put square roots into other register
\end{verbatim}

\index{vroundpd}\index{vroundps}
In a similar way \verb"vroundpd" and \verb"vroundps" retained the syntax with three
operands, the last one being immediate value.
\begin{verbatim}
    vroundps ymm0,ymm1,0011b  ; round toward zero
\end{verbatim}

\index{vpcmpestri}\index{vpcmpestrm}\index{vpcmpistri}\index{vpcmpistrm}
\index{vphminposuw}\index{vpshufd}\index{vpshufhw}\index{vpshuflw}
\index{vcomiss}\index{vcomisd}\index{vcvtss2si}\index{vcvtsd2si}
\index{vcvttss2si}\index{vcvttsd2si}\index{vextractps}\index{vpextrb}
\index{vpextrw}\index{vpextrd}\index{vpextrq}\index{vmovd}
\index{vmovq}\index{vmovntdqa}\index{vmaskmovdqu}\index{vpmovmskb}
\index{vpmovsxbw}\index{vpmovsxbd}\index{vpmovsxbq}\index{vpmovsxwd}
\index{vpmovsxwq}\index{vpmovsxdq}\index{vpmovzxbw}\index{vpmovzxbd}
\index{vpmovzxbq}\index{vpmovzxwd}\index{vpmovzxwq}\index{vpmovzxdq}
Also some of the operations on packed integers kept their two--operand or
three--operand syntax while being promoted to AVX version. In such case these
instructions follow exactly the same rules for operands as their SSE
counterparts (since operations on packed integers do not have 256--bit variants
in AVX extension). These include \verb"vpcmpestri", \verb"vpcmpestrm", \verb"vpcmpistri",
\verb"vpcmpistrm", \verb"vphminposuw", \verb"vpshufd", \verb"vpshufhw", \verb"vpshuflw". And there are
more instructions that in AVX versions keep exactly the same syntax for
operands as the one from SSE, without any additional options: \verb"vcomiss",
\verb"vcomisd", \verb"vcvtss2si", \verb"vcvtsd2si", \verb"vcvttss2si", \verb"vcvttsd2si", \verb"vextractps",
\verb"vpextrb", \verb"vpextrw", \verb"vpextrd", \verb"vpextrq", \verb"vmovd", \verb"vmovq", \verb"vmovntdqa",
\verb"vmaskmovdqu", \verb"vpmovmskb", \verb"vpmovsxbw", \verb"vpmovsxbd", \verb"vpmovsxbq", \verb"vpmovsxwd",
\verb"vpmovsxwq", \verb"vpmovsxdq", \verb"vpmovzxbw", \verb"vpmovzxbd", \verb"vpmovzxbq", \verb"vpmovzxwd",
\verb"vpmovzxwq" and \verb"vpmovzxdq".

\index{vcvtdq2ps}\index{vcvtps2dq}\index{vcvttps2dq}\index{vmovaps}
\index{vmovapd}\index{vmovups}\index{vmovupd}\index{vmovdqa}
\index{vmovdqu}\index{vlddqu}\index{vmovntps}\index{vmovntpd}
\index{vmovntdq}\index{vmovsldup}\index{vmovshdup}\index{vmovmskps}
\index{vmovmskpd}
The move and conversion instructions have mostly been promoted to allow
256--bit size operands in addition to the 128--bit variant with syntax identical
to that from SSE version of the same instruction. Each of the
\verb"vcvtdq2ps", \verb"vcvtps2dq" and \verb"vcvttps2dq",
\verb"vmovaps", \verb"vmovapd", \verb"vmovups", \verb"vmovupd",
\verb"vmovdqa", \verb"vmovdqu", \verb"vlddqu",
\verb"vmovntps", \verb"vmovntpd", \verb"vmovntdq",
\verb"vmovsldup", \verb"vmovshdup",
\verb"vmovmskps" and \verb"vmovmskpd" inherits the 128--bit
syntax from SSE without any changes, and also allows a new form with 256--bit
operands in place of 128--bit ones.
\begin{verbatim}
    vmovups [edi],ymm6        ; store unaligned 256-bit data
\end{verbatim}

\index{vmovddup}
\verb"vmovddup" has the identical 128--bit syntax as its SSE version, and it also
has a 256--bit version, which stores the duplicates of the lowest quad word
from the source operand in the lower half of destination operand, and in the
upper half of destination the duplicates of the low quad word from the upper
half of source. Both source and destination operands need then to be 256--bit
values.

\index{vmovlhps}\index{vmovhlps}
\verb"vmovlhps" and \verb"vmovhlps" have only 128--bit versions, and each takes three
operands, which all must be SSE registers. \verb"vmovlhps" copies two single
precision values from the low quad word of second source register to the high
quad word of destination register, and copies the low quad word of first
source register into the low quad word of destination register. \verb"vmovhlps"
copies two single  precision values from the high quad word of second source
register to the low quad word of destination register, and copies the high
quad word of first source register into the high quad word of destination
register.

\index{vmovlps}\index{vmovhps}\index{vmovlpd}\index{vmovhpd}
\verb"vmovlps", \verb"vmovhps", \verb"vmovlpd" and \verb"vmovhpd" have only 128--bit versions and
their syntax varies depending on whether memory operand is a destination or
source. When memory is destination, the syntax is identical to the one of
equivalent SSE instruction, and when memory is source, the instruction requires
three operands, first two being SSE registers and the third one 64--bit memory.
The value put into destination is then the value copied from first source with
either low or high quad word replaced with value from second source (the
memory operand).
\begin{verbatim}
    vmovhps [esi],xmm7       ; store upper half to memory
    vmovlps xmm0,xmm7,[ebx]  ; low from memory, rest from register
\end{verbatim}

\index{vmovss}\index{vmovsd}
\verb"vmovss" and \verb"vmovsd" have syntax identical to their SSE equivalents as long
as one of the operands is memory, while the versions that operate purely on
registers require three operands (each being SSE register). The value stored
in destination is then the value copied from first source with lowest data
element replaced with the lowest value from second source.
\begin{verbatim}
    vmovss xmm3,[edi]        ; low from memory, rest zeroed
    vmovss xmm0,xmm1,xmm2    ; one value from xmm2, three from xmm1
\end{verbatim}

\index{vcvtss2sd}\index{vcvtsd2ss}\index{vcvtsi2ss}\index{vcvtsi2d}
\verb"vcvtss2sd", \verb"vcvtsd2ss", \verb"vcvtsi2ss" and \verb"vcvtsi2d" use the three--operand
syntax, where destination and first source are always SSE registers, and the
second source follows the same rules and the source in syntax of equivalent
SSE instruction. The value stored in destination is then the value copied from
first source with lowest data element replaced with the result of conversion.
\begin{verbatim}
    vcvtsi2sd xmm4,xmm4,ecx  ; 32-bit integer to 64-bit float
    vcvtsi2ss xmm0,xmm0,rax  ; 64-bit integer to 32-bit float
\end{verbatim}

\index{vcvtdq2pd}\index{vcvtps2pd}\index{vcvtpd2dq}\index{vcvttpd2dq}\index{vcvtpd2ps}
\verb"vcvtdq2pd" and \verb"vcvtps2pd" allow the same syntax as their SSE equivalents,
plus the new variants with AVX register as destination and SSE register or
128--bit memory as source. Analogously \verb"vcvtpd2dq", \verb"vcvttpd2dq" and
\verb"vcvtpd2ps", in addition to variant with syntax identical to SSE version,
allow a variant with SSE register as destination and AVX register or 256--bit
memory as source.

\index{vinsertps}\index{vpinsrb}\index{vpinsrw}\index{vpinsrd}\index{vpinsrq}\index{vpblendw}
\verb"vinsertps", \verb"vpinsrb", \verb"vpinsrw", \verb"vpinsrd", \verb"vpinsrq" and \verb"vpblendw" use
a syntax with four operands, where destination and first source have to be SSE
registers, and the third and fourth operand follow the same rules as second
and third operand in the syntax of equivalent SSE instruction. Value stored in
destination is the the value copied from first source with some data elements
replaced with values extracted from the second source, analogously to the
operation of corresponding SSE instruction.
\begin{verbatim}
    vpinsrd xmm0,xmm0,eax,3  ; insert double word
\end{verbatim}

\index{vblendvps}\index{vblendvpd}\index{vpblendvb}
\verb"vblendvps", \verb"vblendvpd" and \verb"vpblendvb" use a new syntax with four register
operands: destination, two sources and a mask, where second source can also be
a memory operand. \verb"vblendvps" and \verb"vblendvpd" have 256--bit variant, where
operands are AVX registers or 256--bit memory, as well as 128--bit variant,
which has operands being SSE registers or 128--bit memory. \verb"vpblendvb" has only
a 128--bit variant. Value stored in destination is the value copied from the
first source with some data elements replaced, according to mask, by values
from the second source.
\begin{verbatim}
    vblendvps ymm3,ymm1,ymm2,ymm7  ; blend according to mask
\end{verbatim}

\index{vptest}\index{vtestps}\index{vtestpd}
\verb"vptest" allows the same syntax as its SSE version and also has a 256--bit
version, with both operands doubled in size. There are also two new
instructions, \verb"vtestps" and \verb"vtestpd", which perform analogous tests, but only
of the sign bits of corresponding single precision or double precision values,
and set the ZF and CF accordingly. They follow the same syntax rules as
\verb"vptest".
\begin{verbatim}
    vptest ymm0,yword [ebx]  ; test 256-bit values
    vtestpd xmm0,xmm1        ; test sign bits of 64-bit floats
\end{verbatim}

\index{vbroadcastss}\index{vbroadcastsd}\index{vbroadcastf128}
\verb"vbroadcastss", \verb"vbroadcastsd" and \verb"vbroadcastf128" are new instructions,
which broadcast the data element defined by source operand into all elements
of corresponing size in the destination register. \verb"vbroadcastss" needs
source to be 32--bit memory and destination to be either SSE or AVX register.
\verb"vbroadcastsd" requires 64--bit memory as source, and AVX register as
destination. \verb"vbroadcastf128" requires 128--bit memory as source, and AVX
register as destination.
\begin{verbatim}
    vbroadcastss ymm0,dword [eax]  ; get eight copies of value
\end{verbatim}

\index{vinsertf128}
\verb"vinsertf128" is the new instruction, which takes four operands. The
destination and first source have to be AVX registers, second source can be
SSE register or 128--bit memory location, and fourth operand should be an
immediate value. It stores in destination the value obtained by taking
contents of first source and replacing one of its 128--bit units with value of
the second source. The lowest bit of fourth operand specifies at which
position that replacement is done (either 0 or 1).

\index{vextractf128}
\verb"vextractf128" is the new instruction with three operands. The destination
needs to be SSE register or 128--bit memory location, the source must be AVX
register, and the third operand should be an immediate value. It extracts
into destination one of the 128--bit units from source. The lowest bit of third
operand specifies, which unit is extracted.

\index{vmaskmovps}\index{vmaskmovpd}
\verb"vmaskmovps" and \verb"vmaskmovpd" are the new instructions with three operands
that selectively store in destination the elements from second source
depending on the sign bits of corresponding elements from first source. These
instructions can operate on either 128--bit data (SSE registers) or 256--bit
data (AVX registers). Either destination or second source has to be a memory
location of appropriate size, the two other operands should be registers.
\begin{verbatim}
    vmaskmovps [edi],xmm0,xmm5  ; conditionally store
    vmaskmovpd ymm5,ymm0,[esi]  ; conditionally load
\end{verbatim}

\index{vpermilpd}\index{vpermilps}
\verb"vpermilpd" and \verb"vpermilps" are the new instructions with three operands
that permute the values from first source according to the control fields from
second source and put the result into destination operand. It allows to use
either three SSE registers or three AVX registers as its operands, the second
source can be a memory of size equal to the registers used. In alternative
form the second source can be immediate value and then the first source
can be a memory location of the size equal to destination register.

\index{vperm2f128}
\verb"vperm2f128" is the new instruction with four operands, which selects
128--bit blocks of floating point data from first and second source according
to the bit fields from fourth operand, and stores them in destination.
Destination and first source need to be AVX registers, second source can be
AVX register or 256--bit memory area, and fourth operand should be an immediate
value.
\begin{verbatim}
    vperm2f128 ymm0,ymm6,ymm7,12h  ; permute 128-bit blocks
\end{verbatim}

\index{vzeroall}\index{vzeroupper}
\verb"vzeroall" instruction sets all the AVX registers to zero. \verb"vzeroupper" sets
the upper 128--bit portions of all AVX registers to zero, leaving the SSE
registers intact. These new instructions take no operands.

\index{vldmxcsr}\index{vstmxcsr}
\verb"vldmxcsr" and \verb"vstmxcsr" are the AVX versions of \verb"ldmxcsr" and \verb"stmxcsr"
instructions. The rules for their operands remain unchanged.


\subsection{AVX2 instructions}

The AVX2 extension allows all the AVX instructions operating on packed integers
to use 256--bit data types, and introduces some new instructions as well.

The AVX instructions that operate on packed integers and had only a 128--bit
variants, have been supplemented with 256--bit variants, and thus their syntax
rules became analogous to AVX instructions operating on packed floating point
types.
\begin{verbatim}
    vpsubb ymm0,ymm0,[esi]   ; substract 32 packed bytes
    vpavgw ymm3,ymm0,ymm2    ; average of 16-bit integers
\end{verbatim}
However there are some instructions that have not been equipped with the
256--bit variants. \verb"vpcmpestri", \verb"vpcmpestrm", \verb"vpcmpistri", \verb"vpcmpistrm",
\verb"vpextrb", \verb"vpextrw", \verb"vpextrd", \verb"vpextrq", \verb"vpinsrb", \verb"vpinsrw", \verb"vpinsrd",
\verb"vpinsrq" and \verb"vphminposuw" are not affected by AVX2 and allow only the
128--bit operands.

The packed shift instructions, which allowed the third operand specifying
amount to be SSE register or 128--bit memory location, use the same rules
for the third operand in their 256--bit variant.
\begin{verbatim}
    vpsllw ymm2,ymm2,xmm4        ; shift words left
    vpsrad ymm0,ymm3,xword [ebx] ; shift double words right
\end{verbatim}

\index{vpsllvd}\index{vpsllvq}\index{vpsrlvd}\index{vpsrlvq}\index{vpsravd}
There are also new packed shift instructions with standard three--operand AVX
syntax, which shift each element from first source by the amount specified in
corresponding element of second source, and store the results in destination.
\verb"vpsllvd" shifts 32-bit elements left, \verb"vpsllvq" shifts 64--bit elements left,
\verb"vpsrlvd" shifts 32-bit elements right logically, \verb"vpsrlvq" shifts 64--bit
elements right logically and \verb"vpsravd" shifts 32-bit elements right
arithmetically.

The sign--extend and zero--extend instructions, which in AVX versions allowed
source operand to be SSE register or a memory of specific size, in the new
256--bit variant need memory of that size doubled or SSE register as source and
AVX register as destination.
\begin{verbatim}
    vpmovzxbq ymm0,dword [esi]   ; bytes to quad words
\end{verbatim}

Also \verb"vmovntdqa" has been upgraded with 256--bit variant, so it allows to
transfer 256--bit value from memory to AVX register, it needs memory address
to be aligned to 32 bytes.

\index{vpmaskmovd}\index{vpmaskmovq}
\verb"vpmaskmovd" and \verb"vpmaskmovq" are the new instructions with syntax identical
to \verb"vmaskmovps" or \verb"vmaskmovpd", and they performs analogous operation on
packed 32--bit or 64--bit values.

\index{vinserti128}\index{vextracti128}\index{vbroadcasti128}\index{vperm2i128}
\verb"vinserti128", \verb"vextracti128", \verb"vbroadcasti128" and \verb"vperm2i128" are the new
instructions with syntax identical to \verb"vinsertf128", \verb"vextractf128",
\verb"vbroadcastf128" and \verb"vperm2f128" respectively, and they perform analogous
operations on 128--bit blocks of integer data.

\verb"vbroadcastss" and \verb"vbroadcastsd" instructions have been extended to allow
SSE register as a source operand (which in AVX could only be a memory).

\index{vpbroadcastb}\index{vpbroadcastw}\index{vpbroadcastd}\index{vpbroadcastq}
\verb"vpbroadcastb", \verb"vpbroadcastw", \verb"vpbroadcastd" and \verb"vpbroadcastq" are the
new instructions which broadcast the byte, word, double word or quad word from
the source operand into all elements of corresponing size in the destination
register. The destination operand can be either SSE or AVX register, and the
source operand can be SSE register or memory of size equal to the size of data
element.
\begin{verbatim}
    vpbroadcastb ymm0,byte [ebx]  ; get 32 identical bytes
\end{verbatim}

\index{vpermd}\index{vpermps}
\verb"vpermd" and \verb"vpermps" are new three--operand instructions, which use each
32--bit element from first source as an index of element in second source which
is copied into destination at position corresponding to element containing
index. The destination and first source have to be AVX registers, and the
second source can be AVX register or 256--bit memory.

\index{vpermq}\index{vpermpd}
\verb"vpermq" and \verb"vpermpd" are new three--operand instructions, which use 2--bit
indexes from the immediate value specified as third operand to determine which
element from source store at given position in destination. The destination
has to be AVX register, source can be AVX register or 256--bit memory, and the
third operand must be 8--bit immediate value.

The family of new instructions performing \verb"gather" operation have special
syntax, as in their memory operand they use addressing mode that is unique to
them. The base of address can be a 32--bit or 64--bit general purpose register
(the latter only in long mode), and the index (possibly multiplied by scale
value, as in standard addressing) is specified by SSE or AVX register. It is
possible to use only index without base and any numerical displacement can be
added to the address. Each of those instructions takes three operands. First
operand is the destination register, second operand is memory addressed with
a vector index, and third operand is register containing a mask. The most
significant bit of each element of mask determines whether a value will be
loaded from memory into corresponding element in destination. The address of
each element to load is determined by using the corresponding element from
index register in memory operand to calculate final address with given base
and displacement. When the index register contains less elements than the
destination and mask registers, the higher elements of destination are zeroed.
After the value is successfuly loaded, the corresponding element in mask
register is set to zero. The destination, index and mask should all be
distinct registers, it is not allowed to use the same register in two
different roles.

\index{vgatherdps}
\verb"vgatherdps" loads single precision floating point values addressed by
32--bit indexes. The destination, index and mask should all be registers of the
same type, either SSE or AVX. The data addressed by memory operand is 32--bit
in size.
\begin{verbatim}
    vgatherdps xmm0,[eax+xmm1],xmm3    ; gather four floats
    vgatherdps ymm0,[ebx+ymm7*4],ymm3  ; gather eight floats
\end{verbatim}

\index{vgatherqps}
\verb"vgatherqps" loads single precision floating point values addressed by
64--bit indexes. The destination and mask should always be SSE registers, while
index register can be either SSE or AVX register. The data addressed by memory
operand is 32--bit in size.
\begin{verbatim}
    vgatherqps xmm0,[xmm2],xmm3        ; gather two floats
    vgatherqps xmm0,[ymm2+64],xmm3     ; gather four floats
\end{verbatim}

\index{vgatherdpd}
\verb"vgatherdpd" loads double precision floating point values addressed by
32--bit indexes. The index register should always be SSE register, the
destination and mask should be two registers of the same type, either SSE or
AVX. The data addressed by memory operand is 64--bit in size.
\begin{verbatim}
    vgatherdpd xmm0,[ebp+xmm1],xmm3    ; gather two doubles
    vgatherdpd ymm0,[xmm3*8],ymm5      ; gather four doubles
\end{verbatim}

\index{vgatherqpd}
\verb"vgatherqpd" loads double precision floating point values addressed by
64--bit indexes. The destination, index and mask should all be registers of the
same type, either SSE or AVX. The data addressed by memory operand is 64--bit
in size.

\index{vpgatherdd}\index{vpgatherqd}
\verb"vpgatherdd" and \verb"vpgatherqd" load 32--bit values addressed by either 32--bit
or 64--bit indexes. They follow the same rules as \verb"vgatherdps" and \verb"vgatherqps"
respectively.

\index{vpgatherdq}\index{vpgatherqq}
\verb"vpgatherdq" and \verb"vpgatherqq" load 64--bit values addressed by either 32--bit
or 64--bit indexes. They follow the same rules as \verb"vgatherdpd" and \verb"vgatherqpd"
respectively.


\subsection{Auxiliary sets of computational instructions}

There is a number of additional instruction set extensions related to
AVX. They introduce new vector instructions (and sometimes also their SSE
equivalents that use classic instruction encoding), and even some new
instructions operating on general registers that use the AVX--like encoding
allowing the extended syntax with separate destination and source operands.
The CPU support for each of these instruction sets needs to be determined
separately.

The AES extension provides a specialized set of instructions for the
purpose of cryptographic computations defined by Advanced Encryption Standard.
Each of these instructions has two versions: the AVX one and the one with
SSE--like syntax that uses classic encoding. Refer to the Intel manuals for the
details of operation of these instructions.

\index{aesenc}\index{aesenclast}\index{vaesenc}\index{vaesenclast}
\verb"aesenc" and \verb"aesenclast" perform a single round of AES encryption on data
from first source with a round key from second source, and store result in
destination. The destination and first source are SSE registers, and the
second source can be SSE register or 128--bit memory. The AVX versions of these
instructions, \verb"vaesenc" and \verb"vaesenclast", use the syntax with three operands,
while the SSE--like version has only two operands, with first operand being
both the destination and first source.

\index{aesdec}\index{aesdeclast}
\verb"aesdec" and \verb"aesdeclast" perform a single round of AES decryption on data
from first source with a round key from second source. The syntax rules for
them and their AVX versions are the same as for \verb"aesenc".

\index{aesimc}\index{vaesimc}
\verb"aesimc" performs the InvMixColumns transformation of source operand and
store the result in destination. Both \verb"aesimc" and \verb"vaesimc" use only two
operands, destination being SSE register, and source being SSE register or
128--bit memory location.

\index{aeskeygenassist}
\verb"aeskeygenassist" is a helper instruction for generating the round key.
It needs three operands: destination being SSE register, source being SSE
register or 128--bit memory, and third operand being 8--bit immediate value.
The AVX version of this instruction uses the same syntax.

\index{pclmulqdq}\index{vpclmulqdq}
The CLMUL extension introduces just one instruction, \verb"pclmulqdq", and its
AVX version as well. This instruction performs a carryless multiplication of
two 64--bit values selected from first and second source according to the bit
fields in immediate value. The destination and first source are SSE registers,
second source is SSE register or 128--bit memory, and immediate value is
provided as last operand. \verb"vpclmulqdq" takes four operands, while \verb"pclmulqdq"
takes only three operands, with the first one serving both the role of
destination and first source.

The FMA (Fused Multiply--Add) extension introduces additional AVX
instructions which perform multiplication and summation as single operation.
Each one takes three operands, first one serving both the role of destination
and first source, and the following ones being the second and third source.
The mnemonic of FMA instruction is obtained by appending to \verb"vf" prefix: first
either \verb"m" or \verb"nm" to select whether result of multiplication should be taken
as--is or negated, then either \verb"add" or \verb"sub" to select whether third value
will be added to the product or substracted from the product, then either
\verb"132", \verb"213" or \verb"231" to select which source operands are multiplied and which
one is added or substracted, and finally the type of data on which the
instruction operates, either \verb"ps", \verb"pd", \verb"ss" or \verb"sd". As it was with SSE
instructions promoted to AVX, instructions operating on packed floating point
values allow 128--bit or 256--bit syntax, in former all the operands are SSE
registers, but the third one can also be a 128--bit memory, in latter the
operands are AVX registers and the third one can also be a 256--bit memory.
Instructions that compute just one floating point result need operands to be
SSE registers, and the third operand can also be a memory, either 32--bit for
single precision or 64--bit for double precision.
\begin{verbatim}
    vfmsub231ps ymm1,ymm2,ymm3     ; multiply and substract
    vfnmadd132sd xmm0,xmm5,[ebx]   ; multiply, negate and add
\end{verbatim}
In addition to the instructions created by the rule described above, there are
families of instructions with mnemonics starting with either \verb"vfmaddsub" or
\verb"vfmsubadd", followed by either \verb"132", \verb"213" or \verb"231" and then either \verb"ps" or
\verb"pd" (the operation must always be on packed values in this case). They add
to the result of multiplication or substract from it depending on the position
of value in packed data -- instructions from the \verb"vfmaddsub" group add when the
position is odd and substract when the position is even, instructions from the
\verb"vfmsubadd" group add when the position is even and subtstract when the
position is odd. The rules for operands are the same as for other FMA
instructions.

The FMA4 instructions are similar to FMA, but use syntax with four operands
and thus allow destination to be different than all the sources. Their
mnemonics are identical to FMA instructions with the \verb"132", \verb"213" or \verb"231" cut
out, as having separate destination operand makes such selection of operands
superfluous. The multiplication is always performed on values from the first
and second source, and then the value from third source is added or
substracted. Either second or third source can be a memory operand, and the
rules for the sizes of operands are the same as for FMA instructions.
\begin{verbatim}
    vfmaddpd ymm0,ymm1,[esi],ymm2  ; multiply and add
    vfmsubss xmm0,xmm1,xmm2,[ebx]  ; multiply and substract
\end{verbatim}

\index{vcvtps2ph}\index{vcvtph2ps}
The F16C extension consists of two instructions, \verb"vcvtps2ph" and
\verb"vcvtph2ps", which convert floating point values between single precision and
half precision (the 16--bit floating point format). \verb"vcvtps2ph" takes three
operands: destination, source, and rounding controls. The third operand is
always an immediate, the source is either SSE or AVX register containing
single precision values, and the destination is SSE register or memory, the
size of memory is 64 bits when the source is SSE register and 128 bits when
the source is AVX register. \verb"vcvtph2ps" takes two operands, the destination
that can be SSE or AVX register, and the source that is SSE register or memory
with size of the half of destination operand's size.

\index{vfrczps}\index{vfrczss}\index{vfrczpd}\index{vfrczsd}
The AMD XOP extension introduces a number of new vector instructions with
encoding and syntax analogous to AVX instructions. \verb"vfrczps", \verb"vfrczss",
\verb"vfrczpd" and \verb"vfrczsd" extract fractional portions of single or double
precision values, they all take two operands. The packed operations allow
either SSE or AVX register as destination, for the other two it has to be SSE
register. Source can be register of the same type as destination, or memory
of appropriate size (256--bit for destination being AVX register, 128--bit for
packed operation with destination being SSE register, 64--bit for operation
on a solitary double precision value and 32--bit for operation on a solitary
single precision value).
\begin{verbatim}
    vfrczps ymm0,[esi]           ; load fractional parts
\end{verbatim}

\index{vpcmov}
\verb"vpcmov" copies bits from either first or second source into destination
depending on the values of corresponding bits in the fourth operand (the
selector). If the bit in selector is set, the corresponding bit from first
source is copied into the same position in destination, otherwise the bit from
second source is copied. Either second source or selector can be memory
location, 128--bit or 256--bit depending on whether SSE registers or AVX
registers are specified as the other operands.
\begin{verbatim}
    vpcmov xmm0,xmm1,xmm2,[ebx]  ; selector in memory
    vpcmov ymm0,ymm5,[esi],ymm2  ; source in memory
\end{verbatim}
The family of packed comparison instructions take four operands, the
destination and first source being SSE register, second source being SSE
register or 128--bit memory and the fourth operand being immediate value
defining the type of comparison. The mnemonic or instruction is created
by appending to \verb"vpcom" prefix either \verb"b" or \verb"ub" to compare signed or
unsigned bytes, \verb"w" or \verb"uw" to compare signed or unsigned words, \verb"d" or \verb"ud"
to compare signed or unsigned double words, \verb"q" or \verb"uq" to compare signed or
unsigned quad words. The respective values from the first and second source
are compared and the corresponding data element in destination is set to
either all ones or all zeros depending on the result of comparison. The fourth
operand has to specify one of the eight comparison types (table \ref{tab:XOP_comparisons}). All
these instruction have also variants with only three operands and the type
of comparison encoded within the instruction name by inserting the comparison
mnemonic after \verb"vpcom".
\begin{verbatim}
    vpcomb   xmm0,xmm1,xmm2,4    ; test for equal bytes
    vpcomgew xmm0,xmm1,[ebx]     ; compare signed words
\end{verbatim}

\begin{table}[hbt]
\begin{center}\begin{tabular}{|c|c|c|}
\hline
Code & Mnemonic & Description \\
\hline \hline
0 & \verb"lt" & less than \\
\hline
1 & \verb"le" & less than or equal \\
\hline
2 & \verb"gt" & greater than \\
\hline
3 & \verb"ge" & greater than or equal \\
\hline
4 & \verb"eq" & equal \\
\hline
5 & \verb"neq" & not equal \\
\hline
6 & \verb"false" & false \\
\hline
7 & \verb"true" & true \\
\hline
\end{tabular}\end{center}
\caption{XOP comparisons.}
\label{tab:XOP_comparisons}
\end{table}

\index{vpermil2ps}\index{vpermil2pd}
\verb"vpermil2ps" and \verb"vpermil2pd" set the elements in destination register to
zero or to a value selected from first or second source depending on the
corresponding bit fields from the fourth operand (the selector) and the
immediate value provided in fifth operand. Refer to the AMD manuals for the
detailed explanation of the operation performed by these instructions. Each
of the first four operands can be a register, and either second source or
selector can be memory location, 128--bit or 256--bit depending on whether SSE
registers or AVX registers are used for the other operands.
\begin{verbatim}
    vpermil2ps ymm0,ymm3,ymm7,ymm2,0  ; permute from two sources
\end{verbatim}

\index{vphaddbw}\index{vphaddubw}\index{vphaddbd}\index{vphaddubd}
\index{vphaddbq}\index{vphaddubq}\index{vphaddwd}\index{vphadduwd}
\index{vphaddwq}\index{vphadduwq}\index{vphadddq}\index{vphaddudq}
\index{vphsubbw}\index{vphsubwd}\index{vphsubdq}
\verb"vphaddbw" adds pairs of adjacent signed bytes to form 16--bit values and
stores them at the same positions in destination. \verb"vphaddubw" does the same
but treats the bytes as unsigned. \verb"vphaddbd" and \verb"vphaddubd" sum all bytes
(either signed or unsigned) in each four--byte block to 32--bit results,
\verb"vphaddbq" and \verb"vphaddubq" sum all bytes in each eight--byte block to
64--bit results, \verb"vphaddwd" and \verb"vphadduwd" add pairs of words to 32--bit
results, \verb"vphaddwq" and \verb"vphadduwq" sum all words in each four--word block to
64--bit results, \verb"vphadddq" and \verb"vphaddudq" add pairs of double words to 64--bit
results. \verb"vphsubbw" substracts in each two--byte block the byte at higher
position from the one at lower position, and stores the result as a signed
16--bit value at the corresponding position in destination, \verb"vphsubwd"
substracts in each two--word block the word at higher position from the one at
lower position and makes signed 32--bit results, \verb"vphsubdq" substract in each
block of two double word the one at higher position from the one at lower
position and makes signed 64--bit results. Each of these instructions takes
two operands, the destination being SSE register, and the source being SSE
register or 128--bit memory.
\begin{verbatim}
    vphadduwq xmm0,xmm1          ; sum quadruplets of words
\end{verbatim}

\index{vpmacsww}\index{vpmacssww}\index{vpmacsdd}\index{vpmacssdd}
\index{vpmacswd}\index{vpmacsswd}\index{vpmacsdql}\index{vpmacssdql}
\index{vpmacsdqh}\index{vpmacssdqh}\index{vpmadcswd}\index{vpmadcsswd}
\verb"vpmacsww" and \verb"vpmacssww" multiply the corresponding signed 16--bit values
from the first and second source and then add the products to the parallel
values from the third source, then \verb"vpmacsww" takes the lowest 16 bits of the
result and \verb"vpmacssww" saturates the result down to 16--bit value, and they
store the final 16--bit results in the destination. \verb"vpmacsdd" and \verb"vpmacssdd"
perform the analogous operation on 32--bit values. \verb"vpmacswd" and \verb"vpmacsswd" do
the same calculation only on the low 16--bit values from each 32--bit block and
form the 32--bit results. \verb"vpmacsdql" and \verb"vpmacssdql" perform such operation
on the low 32--bit values from each 64--bit block and form the 64--bit results,
while \verb"vpmacsdqh" and \verb"vpmacssdqh" do the same on the high 32--bit values from
each 64--bit block, also forming the 64--bit results. \verb"vpmadcswd" and
\verb"vpmadcsswd" multiply the corresponding signed 16--bit value from the first
and second source, then sum all the four products and add this sum to each
16--bit element from third source, storing the truncated or saturated result
in destination. All these instructions take four operands, the second source
can be 128--bit memory or SSE register, all the other operands have to be
SSE registers.
\begin{verbatim}
    vpmacsdd xmm6,xmm1,[ebx],xmm6  ; accumulate product
\end{verbatim}

\index{vpperm}
\verb"vpperm" selects bytes from first and second source, optionally applies a
separate transformation to each of them, and stores them in the destination.
The bit fields in fourth operand (the selector) specify for each position in
destination what byte from which source is taken and what operation is applied
to it before it is stored there. Refer to the AMD manuals for the detailed
information about these bit fields. This instruction takes four operands,
either second source or selector can be a 128--bit memory (or they can be SSE
registers both), all the other operands have to be SSE registers.

\index{vpshlb}\index{vpshlw}\index{vpshld}\index{vpshlq}
\verb"vpshlb", \verb"vpshlw", \verb"vpshld" and \verb"vpshlq" shift logically bytes, words, double
words or quad words respectively. The amount of bits to shift by is specified
for each element separately by the signed byte placed at the corresponding
position in the third operand. The source containing elements to shift is
provided as second operand. Either second or third operand can be 128--bit
memory (or they can be SSE registers both) and the other operands have to be
SSE registers.
\begin{verbatim}
    vpshld xmm3,xmm1,[ebx]       ; shift bytes from xmm1
\end{verbatim}

\index{vpshab}\index{vpshaw}\index{vpshad}\index{vpshaq}
\index{vprotb}\index{vprotw}\index{vprotd}\index{vprotq}
\verb"vpshab", \verb"vpshaw", \verb"vpshad" and \verb"vpshaq" arithmetically shift bytes, words,
double words or quad words. These instructions follow the same rules as the
logical shifts described above. \verb"vprotb", \verb"vprotw", \verb"vprotd" and \verb"vprotq"
rotate bytes, word, double words or quad words. They follow the same rules as
shifts, but additionally allow third operand to be immediate value, in which
case the same amount of rotation is specified for all the elements in source.
\begin{verbatim}
    vprotb xmm0,[esi],3          ; rotate bytes to the left
\end{verbatim}

\index{movbe}
The MOVBE extension introduces just one new instruction, \verb"movbe", which
swaps bytes in value from source before storing it in destination, so can
be used to load and store big endian values. It takes two operands, either
the destination or source should be a 16--bit, 32--bit or 64--bit memory (the
last one being only allowed in long mode), and the other operand should be
a general register of the same size.

The BMI extension, consisting of two subsets -- BMI1 and BMI2, introduces
new instructions operating on general registers, which use the same encoding
as AVX instructions and so allow the extended syntax. All these instructions
use 32--bit operands, and in long mode they also allow the forms with 64--bit
operands.

\index{andn}
\verb"andn" calculates the bitwise AND of second source with the inverted bits
of first source and stores the result in destination. The destination and
the first source have to be general registers, the second source can be
general register or memory.
\begin{verbatim}
    andn edx,eax,[ebx]   ; bit-multiply inverted eax with memory
\end{verbatim}

\index{bextr}
\verb"bextr" extracts from the first source the sequence of bits using an index
and length specified by bit fields in the second source operand and stores
it into destination. The lowest 8 bits of second source specify the position
of bit sequence to extract and the next 8 bits of second source specify the
length of sequence. The first source can be a general register or memory,
the other two operands have to be general registers.
\begin{verbatim}
    bextr eax,[esi],ecx  ; extract bit field from memory
\end{verbatim}

\index{blsi}
\verb"blsi" extracts the lowest set bit from the source, setting all the other
bits in destination to zero. The destination must be a general register,
the source can be general register or memory.
\begin{verbatim}
    blsi rax,r11         ; isolate the lowest set bit
\end{verbatim}

\index{blsmsk}\index{blsr}
\verb"blsmsk" sets all the bits in the destination up to the lowest set bit in
the source, including this bit. \verb"blsr" copies all the bits from the source to
destination except for the lowest set bit, which is replaced by zero. These
instructions follow the same rules for operands as \verb"blsi".

\index{tzcnt}\index{lzcnt}
\verb"tzcnt" counts the number of trailing zero bits, that is the zero bits up to
the lowest set bit of source value. This instruction is analogous to \verb"lzcnt"
and follows the same rules for operands, so it also has a 16--bit version,
unlike the other BMI instructions.

\index{bzhi}
\verb"bzhi" is BMI2 instruction, which copies the bits from first source to
destination, zeroing all the bits up from the position specified by second
source. It follows the same rules for operands as \verb"bextr".

\index{pext}\index{pdep}
\verb"pext" uses a mask in second source operand to select bits from first
operands and puts the selected bits as a continuous sequence into destination.
\verb"pdep" performs the reverse operation -- it takes sequence of bits from the
first source and puts them consecutively at the positions where the bits in
second source are set, setting all the other bits in destination to zero.
These BMI2 instructions follow the same rules for operands as \verb"andn".

\index{mulx}
\verb"mulx" is a BMI2 instruction which performs an unsigned multiplication of
value from EDX or RDX register (depending on the size of specified operands)
by the value from third operand, and stores the low half of result in the
second operand, and the high half of result in the first operand, and it does
it without affecting the flags. The third operand can be general register or
memory, and both the destination operands have to be general registers.
\begin{verbatim}
    mulx edx,eax,ecx     ; multiply edx by ecx into edx:eax
\end{verbatim}

\index{shlx}\index{shrx}\index{sarx}
\verb"shlx", \verb"shrx" and \verb"sarx" are BMI2 instructions, which perform logical or
arithmetical shifts of value from first source by the amount specified by
second source, and store the result in destination without affecting the
flags. The have the same rules for operands as \verb"bzhi" instruction.

\index{rorx}
\verb"rorx" is a BMI2 instruction which rotates right the value from source
operand by the constant amount specified in third operand and stores the
result in destination without affecting the flags. The destination operand
has to be general register, the source operand can be general register or
memory, and the third operand has to be an immediate value.
\begin{verbatim}
    rorx eax,edx,7       ; rotate without affecting flags
\end{verbatim}

\index{blsic}\index{blsfill}
The TBM is an extension designed by AMD to supplement the BMI set. The
\verb"bextr" instruction is extended with a new form, in which second source is
a 32--bit immediate value. \verb"blsic" is a new instruction which performs the
same operation as \verb"blsi", but with the bits of result reversed. It uses the
same rules for operands as \verb"blsi". \verb"blsfill" is a new instruction, which takes
the value from source, sets all the bits below the lowest set bit and store
the result in destination, it also uses the same rules for operands as \verb"blsi".

\index{blci}\index{blcic}\index{blcs}\index{blcmsk}\index{blcfill}
\verb"blci", \verb"blcic", \verb"blcs", \verb"blcmsk" and \verb"blcfill" are instructions analogous
to \verb"blsi", \verb"blsic", \verb"blsr", \verb"blsmsk" and \verb"blsfill" respectively, but they
perform the bit--inverted versions of the same operations. They follow the
same rules for operands as the instructions they reflect.

\index{tzmsk}\index{t1mskc}
\verb"tzmsk" finds the lowest set bit in value from source operand, sets all bits
below it to 1 and all the rest of bits to zero, then writes the result to
destination. \verb"t1mskc" finds the least significant zero bit in the value from
source  operand, sets the bits below it to zero and all the other bits to 1,
and writes the result to destination. These instructions have the same rules
for operands as \verb"blsi".


\subsection{Other extensions of instruction set}

There is a number of additional instruction set extensions recognized by flat
assembler, and the general syntax of the instructions introduced by those
extensions is provided here. For a detailed information on the operations
performed by them, check out the manuals from Intel (for the VMX, SMX, XSAVE,
RDRAND, FSGSBASE, INVPCID, HLE and RTM extensions) or AMD (for the SVM extension).

\index{vmxon}\index{vmxoff}\index{vmlaunch}\index{vmresume}\index{vmcall}
The Virtual--Machine Extensions (VMX) provide a set of instructions for the
management of virtual machines. The \verb"vmxon" instruction, which enters the VMX
operation, requires a single 64--bit memory operand, which should be a physical
address of memory region, which the logical processor may use to support VMX
operation. The \verb"vmxoff" instruction, which leaves the VMX operation, has no
operands. The \verb"vmlaunch" and \verb"vmresume", which launch or resume the virtual
machines, and \verb"vmcall", which allows guest software to call the VM monitor,
use no operands either.

\index{vmptrld}\index{vmptrst}\index{vmclear}
The \verb"vmptrld" loads the physical address of current Virtual Machine Control
Structure (VMCS) from its memory operand, \verb"vmptrst" stores the pointer to
current VMCS into address specified by its memory operand, and \verb"vmclear" sets
the launch state of the VMCS referenced by its memory operand to clear. These
three instruction all require single 64--bit memory operand.

\index{vmread}\index{vmwrite}
The \verb"vmread" reads from VCMS a field specified by the source operand and
stores it into the destination operand. The source operand should be a
general purpose register, and the destination operand can be a register of
memory. The \verb"vmwrite" writes into a VMCS field specified by the destination
operand the value provided by source operand. The source operand can be a
general purpose register or memory, and the destination operand must be a
register. The size of operands for those instructions should be 64--bit when
in long mode, and 32--bit otherwise.

\index{invept}\index{invvpid}
The \verb"invept" and \verb"invvpid" invalidate the translation lookaside buffers
(TLBs) and paging--structure caches, either derived from extended page tables
(EPT), or based on the virtual processor identifier (VPID). These instructions
require two operands, the first one being the general purpose register
specifying the type of invalidation, and the second one being a 128--bit
memory operand providing the invalidation descriptor. The first operand
should be a 64--bit register when in long mode, and 32--bit register otherwise.

\index{getsec}
The Safer Mode Extensions (SMX) provide the functionalities available
throught the \verb"getsec" instruction. This instruction takes no operands, and
the function that is executed is determined by the contents of EAX register
upon executing this instruction.

\index{skinit}
The Secure Virtual Machine (SVM) is a variant of virtual machine extension
used by AMD. The \verb"skinit" instruction securely reinitializes the processor
allowing the startup of trusted software, such as the virtual machine monitor
(VMM). This instruction takes a single operand, which must be EAX, and
provides a physical address of the secure loader block (SLB).

\index{vmrun}\index{vmsave}\index{vmload}
The \verb"vmrun" instruction is used to start a guest virtual machine,
its only operand should be an accumulator register (AX, EAX or RAX, the
last one available only in long mode) providing the physical address of the
virtual machine control block (VMCB). The \verb"vmsave" stores a subset of
processor state into VMCB specified by its operand, and \verb"vmload" loads the
same subset of processor state from a specified VMCB. The same operand rules
as for the \verb"vmrun" apply to those two instructions.

\index{vmmcall}
\verb"vmmcall" allows the guest software to call the VMM. This instruction takes
no operands.

\index{stgi}\index{clgi}
\verb"stgi" set the global interrupt flag to 1, and \verb"clgi" zeroes it. These
instructions take no operands.

\index{invlpga}
\verb"invlpga" invalidates the TLB mapping for a virtual page specified by the
first operand (which has to be accumulator register) and address space
identifier specified by the second operand (which must be ECX register).

\index{xsave}\index{xsaveopt}\index{xrstor}\index{xsave64}\index{xsaveopt64}\index{xrstor64}
The XSAVE set of instructions allows to save and restore processor state
components. \verb"xsave" and \verb"xsaveopt" store the components of processor state
defined by bit mask in EDX and EAX registers into area defined by memory
operand. \verb"xrstor" restores from the area specified by memory operand the
components of processor state defined by mask in EDX and EAX. The \verb"xsave64",
\verb"xsaveopt64" and \verb"xrstor64" are 64--bit versions of these instructions, allowed
only in long mode.

\index{xgetbv}\index{xsetbv}
\verb"xgetbv" read the contents of 64--bit XCR (extended control register)
specified in ECX register into EDX and EAX registers. \verb"xsetbv" writes the
contents of EDX and EAX into the 64--bit XCR specified by ECX register. These
instructions have no operands.

\index{rdrand}
The RDRAND extension introduces one new instruction, \verb"rdrand", which loads
the hardware--generated random value into general register. It takes one
operand, which can be 16--bit, 32--bit or 64--bit register (with the last one
being allowed only in long mode).

\index{rdfsbase}\index{rdgsbase}\index{wrfsbase}\index{wrgsbase}
The FSGSBASE extension adds long mode instructions that allow to read and
write the segment base registers for FS and GS segments. \verb"rdfsbase" and
\verb"rdgsbase" read the corresponding segment base registers into operand, while
\verb"wrfsbase" and \verb"wrgsbase" write the value of operand into those register.
All these instructions take one operand, which can be 32--bit or 64--bit general
register.

\index{invpcid}
The INVPCID extension adds \verb"invpcid" instruction, which invalidates mapping
in the TLBs and paging caches based on the invalidation type specified in
first operand and PCID invalidate descriptor specified in second operand.
The first operands should be 32--bit general register when not in long mode,
or 64--bit general register when in long mode. The second operand should be
128--bit memory location.

\index{xacquire}\index{xrelease}\index{xbegin}\index{xend}\index{xabort}\index{xtest}
The HLE and RTM extensions provide set of instructions for the transactional
management. The \verb"xacquire" and \verb"xrelease" are new prefixes that can be used
with some of the instructions to start or end lock elision on the memory
address specified by prefixed instruction. The \verb"xbegin" instruction starts
the transactional execution, its operand is the address a fallback routine
that gets executes in case of transaction abort, specified like the operand
for near jump instruction. \verb"xend" marks the end of transcational execution
region, it takes no operands. \verb"xabort" forces the transaction abort, it takes
an 8--bit immediate value as its only operand, this value is passed in the
highest bits of EAX to the fallback routine. \verb"xtest" checks whether there is
transactional execution in progress, this instruction takes no operands.


\section{Control directives}
\label{sec:control}
This section describes the directives that control the assembly process, they
are processed during the assembly and may cause some blocks of instructions
to be assembled differently or not assembled at all.

\subsection{Numerical constants}
\index{=}
The \verb"=" directive allows to define the numerical constant. It should be preceded by
the name for the constant and followed by the numerical expression providing the value.
The value of such constants can be a number or an address, but -- unlike labels -- the
numerical constants are not allowed to hold the register--based addresses.
Besides this difference, in their basic variant numerical constants behave
very much like labels and you can even forward--reference them (access their
values before they actually get defined).

There is, however, a second variant of numerical constants, which is recognized by assembler when
you try to define the constant of name, under which there already was a numerical constant defined.
In such case assembler treats that constant as an assembly--time variable and allows it to be
assigned with new value, but forbids forward--referencing it (for obvious reasons). Let's see both the
variant of numerical constants in one example:
\begin{verbatim}
    dd sum
    x = 1
    x = x+2
    sum = x
\end{verbatim}
Here the \verb"x" is an assembly--time variable, and every time it is accessed, the value
that was assigned to it the most recently is used. Thus if we tried to access the \verb"x" before
it gets defined the first time, like if we wrote \verb"dd x" in place of the \verb"dd sum" instruction,
it would cause an error. And when it is re--defined with the \verb"x = x+2" directive, the previous value
of \verb"x" is used to calculate the new one. So when the \verb"sum" constant gets defined, the \verb"x" has
value of 3, and this value is assigned to the \verb"sum". Since this one is defined only once in source,
it is the standard numerical constant, and can be forward--referenced. So the \verb"dd sum" is assembled
as \verb"dd 3". To read more about how the assembler is able to resolve this, see section \ref{sec:passes}.

The value of numerical constant can be preceded by size operator, which can ensure that the value
will fit in the range for the specified size, and can affect also how some of the calculations inside
the numerical expression are performed. This example:
\begin{verbatim}
    c8 = byte -1
    c32 = dword -1
\end{verbatim}
defines two different constants, the first one fits in 8 bits, the second one fits in 32 bits.

When you need to define constant with the value of address, which may be register--based
(and thus you cannot employ numerical constant for this purpose), you can use the extended
syntax of \verb"label" directive (already described in section \ref{sec:labels}), like:
\begin{verbatim}
    label myaddr at ebp+4
\end{verbatim}
which declares label placed at \verb"ebp+4" address. However remember that labels,
unlike numerical constants, cannot become assembly--time variables.


\subsection{Conditional assembly}
\index{IF}
\verb"if" directive causes some block of instructions to be assembled only under
certain condition. It should be followed by logical expression specifying the
condition, instructions in next lines will be assembled only when this
condition is met, otherwise they will be skipped. The optional \verb"else if"
directive followed with logical expression specifying additional condition
begins the next block of instructions that will be assembled if previous
conditions were not met, and the additional condition is met. The optional
\verb"else" directive begins the block of instructions that will be assembled if
all the conditions were not met. The \verb"end if" directive ends the last block of
instructions.

You should note that \verb"if" directive is processed at assembly stage and
therefore it doesn't affect any preprocessor directives, like the definitions
of symbolic constants and macroinstructions -- when the assembler recognizes the
\verb"if" directive, all the preprocessing has been already finished.

The logical expression consist of logical values and logical operators. The
logical operators are \verb"~" for logical negation, \verb"&" for logical and, \verb"|" for
logical or. The negation has the highest priority. Logical value can be a
numerical expression, it will be false if it is equal to zero, otherwise it
will be true. Two numerical expression can be compared using one of the
following operators to make the logical value: \verb"=" (equal), \verb"<" (less),
\verb">" (greater), \verb"<=" (less or equal), \verb">=" (greater or equal),
\verb"<>" (not equal).

The \verb"used" operator followed by a symbol name, is the logical value that
checks whether the given symbol is used somewhere (it returns correct result
even if symbol is used only after this check). The \verb"defined" operator can be
followed by any expression, usually just by a single symbol name; it checks
whether the given expression contains only symbols that are defined in the
source and accessible from the current position.

With \verb"relativeto" operator it is possible to check whether values of two
expressions differ only by constant amount. The valid syntax is a numerical
expression followed by \verb"relativeto" and then another expression (possibly
register-based). Labels that have no simple numerical value can be tested
this way to determine what kind of operations may be possible with them.

The following simple example uses the \verb"count" constant that should be
defined somewhere in source:
\begin{verbatim}
    if count>0
        mov cx,count
        rep movsb
    end if
\end{verbatim}
These two assembly instructions will be assembled only if the \verb"count" constant
is greater than 0. The next sample shows more complex conditional structure:
\begin{verbatim}
    if count & ~ count mod 4
        mov cx,count/4
        rep movsd
    else if count>4
        mov cx,count/4
        rep movsd
        mov cx,count mod 4
        rep movsb
    else
        mov cx,count
        rep movsb
    end if
\end{verbatim}
The first block of instructions gets assembled when the \verb"count" is non zero and
divisible by four, if this condition is not met, the second logical expression,
which follows the \verb"else if", is evaluated and if it's true, the second block
of instructions get assembled, otherwise the last block of instructions, which
follows the line containing only \verb"else", is assembled.

There are also operators that allow comparison of values being any chains of
symbols. The \verb"eq" compares whether two such values are exactly the same.
The \verb"in" operator checks whether given value is a member of the list of values
following this operator, the list should be enclosed between \verb"<" and \verb">"
characters, its members should be separated with commas. The symbols are
considered the same when they have the same meaning for the assembler -- for
example \verb"pword" and \verb"fword" for assembler are the same and thus are not
distinguished by the above operators. In the same way \verb"16 eq 10h" is the true
condition, however \verb"16 eq 10+4" is not.

The \verb"eqtype" operator checks whether the two compared values have the same
structure, and whether the structural elements are of the same type. The
distinguished types include numerical expressions, individual quoted strings,
floating point numbers, address expressions (the expressions enclosed in square
brackets or preceded by \verb"ptr" operator), instruction mnemonics, registers, size
operators, jump type and code type operators. And each of the special
characters that act as a separators, like comma or colon, is the separate type
itself. For example, two values, each one consisting of register name followed
by comma and numerical expression, will be regarded as of the same type, no
matter what kind of register and how complicated numerical expression is used;
with exception for the quoted strings and floating point values, which are the
special kinds of numerical expressions and are treated as different types. Thus
\verb"eax,16 eqtype fs,3+7" condition is true, but \verb"eax,16 eqtype eax,1.6" is false.

\subsection{Repeating blocks of instructions}
\label{sec:repeating}
\index{TIMES}
\verb"times" directive repeats one instruction specified number of times. It
should be followed by numerical expression specifying number of repeats and
the instruction to repeat (optionally colon can be used to separate number and
instruction). When special symbol \verb"%" is used inside the instruction, it is
equal to the number of current repeat. For example \verb"times 5 db %" will define
five bytes with values 1, 2, 3, 4, 5. Recursive use of \verb"times" directive is
also allowed, so \verb"times 3 times % db %" will define six bytes with values
1, 1, 2, 1, 2, 3.

\index{REPEAT}
\verb"repeat" directive repeats the whole block of instructions. It should be
followed by numerical expression specifying number of repeats. Instructions
to repeat are expected in next lines, ended with the \verb"end repeat" directive,
for example:
\begin{verbatim}
    repeat 8
        mov byte [bx],%
        inc bx
    end repeat
\end{verbatim}
The generated code will store byte values from one to eight in the memory
addressed by BX register.

Number of repeats can be zero, in that case the instructions are not
assembled at all.

\index{BREAK}
The \verb"break" directive allows to stop repeating earlier and continue assembly
from the first line after the \verb"end repeat". Combined with the \verb"if" directive it
allows to stop repeating under some special condition, like:
\begin{verbatim}
    s = x/2
    repeat 100
        if x/s = s
            break
        end if
        s = (s+x/s)/2
    end repeat
\end{verbatim}

\index{WHILE}
The \verb"while" directive repeats the block of instructions as long as the
condition specified by the logical expression following it is true. The block
of instructions to be repeated should end with the \verb"end while" directive.
Before each repetition the logical expression is evaluated and when its value
is false, the assembly is continued starting from the first line after the
\verb"end while". Also in this case the \verb"%" symbol holds the number of current
repeat. The \verb"break" directive can be used to stop this kind of loop in the same
way as with \verb"repeat" directive. The previous sample can be rewritten to use the
\verb"while" instead of \verb"repeat" this way:
\begin{verbatim}
    s = x/2
    while x/s <> s
        s = (s+x/s)/2
        if % = 100
            break
        end if
    end while
\end{verbatim}

The blocks defined with \verb"if", \verb"repeat" and \verb"while" can be nested in any order,
however they should be closed in the same order in which they were started. The
\verb"break" directive always stops processing the block that was started last with
either the \verb"repeat" or \verb"while" directive.

\subsection{Addressing spaces}
\index{ORG}
\verb"org" directive sets address at which the following code is expected to
appear in memory. It should be followed by numerical expression specifying
the address. This directive begins the new addressing space, the following
code itself is not moved in any way, but all the labels defined within it
and the value of \verb"$" symbol are affected as if it was put at the given
address. However it's the responsibility of programmer to put the code at
correct address at run--time.

\index{LOAD}
The \verb"load" directive allows to define constant with a binary value loaded
from the already assembled code. This directive should be followed by the name
of the constant, then optionally size operator, then \verb"from" operator and a
numerical expression specifying a valid address in current addressing space.
The size operator has unusual meaning in this case -- it states how many bytes
(up to 8) have to be loaded to form the binary value of constant. If no size
operator is specified, one byte is loaded (thus value is in range from 0 to
255). The loaded data cannot exceed current offset.

\index{STORE}
The \verb"store" directive can modify the already generated code by replacing
some of the previously generated data with the value defined by given
numerical expression, which follows. The expression can be preceded by the
optional size operator to specify how large value the expression defines, and
therefore how much bytes will be stored, if there is no size operator, the
size of one byte is assumed. Then the \verb"at" operator and the numerical
expression defining the valid address in current addressing code space, at
which the given value have to be stored should follow. This is a directive for
advanced appliances and should be used carefully.

Both \verb"load" and \verb"store" directives are limited to operate on places in
current addressing space. The \verb"$$" symbol is always equal to the base address
of current addressing space, and the \verb"$" symbol is the address of current
position in that addressing space, therefore these two values define limits
of the area, where \verb"load" and \verb"store" can operate.

Combining the \verb"load" and \verb"store" directives allows to do things like encoding
some of the already generated code. For example to encode the whole code
generated in current addressing space you can use such block of directives:
\begin{verbatim}
    repeat $-$$
        load a byte from $$+%-1
        store byte a xor c at $$+%-1
    end repeat
\end{verbatim}
and each byte of code will be xored with the value defined by \verb"c" constant.

\index{VIRTUAL}
\verb"virtual" defines virtual data at specified address. This data will not be
included in the output file, but labels defined there can be used in other
parts of source. This directive can be followed by \verb"at" operator and the
numerical expression specifying the address for virtual data, otherwise is
uses current address, the same as \verb"virtual at $". Instructions defining data
are expected in next lines, ended with \verb"end virtual" directive. The block of
virtual instructions itself is an independent addressing space, after it's
ended, the context of previous addressing space is restored.

The \verb"virtual" directive can be used to create union of some variables, for
example:
\begin{verbatim}
    GDTR dp ?
    virtual at GDTR
        GDT_limit dw ?
        GDT_address dd ?
    end virtual
\end{verbatim}
It defines two labels for parts of the 48--bit variable at \verb"GDTR" address.

It can be also used to define labels for some structures addressed by a
register, for example:
\begin{verbatim}
    virtual at bx
        LDT_limit dw ?
        LDT_address dd ?
    end virtual
\end{verbatim}
With such definition instruction \verb"mov ax,[LDT_limit]" will be assembled
to the same instruction as \verb"mov ax,[bx]".

Declaring defined data values or instructions inside the virtual block would
also be useful, because the \verb"load" directive can be used to load the values
from the virtually generated code into a constants. This directive should be
used after the code it loads but before the virtual block ends, because it can
only load the values from the same addressing space. For example:
\begin{verbatim}
    virtual at 0
        xor eax,eax
        and edx,eax
        load zeroq dword from 0
    end virtual
\end{verbatim}
The above piece of code will define the \verb"zeroq" constant containing four bytes
of the machine code of the instructions defined inside the virtual block.
This method can be also used to load some binary value from external file.
For example this code:
\begin{verbatim}
    virtual at 0
        file 'a.txt':10h,1
        load char from 0
    end virtual
\end{verbatim}
loads the single byte from offset 10h in file \verb"a.txt" into the \verb"char"
constant.

Any of the \verb"section" directives described in \ref{sec:formatter} also begins a new
addressing space.

\subsection{Other directives}
\label{sec:other}
\index{ALIGN}
\verb"align" directive aligns code or data to the specified boundary. It should
be followed by a numerical expression specifying the number of bytes, to the
multiply of which the current address has to be aligned. The boundary value
has to be the power of two.

The \verb"align" directive fills the bytes that had to be skipped to perform the
alignment with the \verb"nop" instructions and at the same time marks this area as
uninitialized data, so if it is placed among other uninitialized data that
wouldn't take space in the output file, the alignment bytes will act the same
way. If you need to fill the alignment area with some other values, you can
combine \verb"align" with \verb"virtual" to get the size of alignment needed and then
create the alignment yourself, like:
\begin{verbatim}
    virtual
        align 16
        a = $ - $$
    end virtual
    db a dup 0
\end{verbatim}
The \verb"a" constant is defined to be the difference between address after alignment
and address of the \verb"virtual" block (see previous section), so it is equal to
the size of needed alignment space.

\index{DISPLAY}
\verb"display" directive displays the message at the assembly time. It should
be followed by the quoted strings or byte values, separated with commas. It
can be used to display values of some constants, for example:
\begin{verbatim}
    bits = 16
    display 'Current offset is 0x'
    repeat bits/4
        d = '0' + $ shr (bits-%*4) and 0Fh
        if d > '9'
            d = d + 'A'-'9'-1
        end if
        display d
    end repeat
    display 13,10
\end{verbatim}
This block of directives calculates the four hexadecimal digits of 16--bit value
and converts them into characters for displaying. Note that this will not work if
the adresses in current addressing space are relocatable (as it might happen with
PE or object output formats), since only absolute values can be used this way.
The absolute value may be obtained by calculating the relative address, like
\verb"$-$$", or \verb"rva $" in case of PE format.

The \verb"err" directive immediately terminates the assembly process when it is
encountered by assembler.

The \verb"assert" directive tests whether the logical expression that follows it
is true, and if not, it signalizes the error.


\subsection{Multiple passes}
\label{sec:passes}
Because the assembler allows to reference some of the labels or constants
before they get actually defined, it has to predict the values of such labels
and if there is even a suspicion that prediction failed in at least one case,
it does one more pass, assembling the whole source, this time doing better
prediction based on the values the labels got in the previous pass.

The changing values of labels can cause some instructions to have encodings
of different length, and this can cause the change in values of labels again.
And since the labels and constants can also be used inside the expressions that
affect the behavior of control directives, the whole block of source can be
processed completely differently during the new pass. Thus the assembler does
more and more passes, each time trying to do better predictions to approach
the final solution, when all the values get predicted correctly. It uses
various method for predicting the values, which has been chosen to allow
finding in a few passes the solution of possibly smallest length for the most
of the programs.

Some of the errors, like the values not fitting in required boundaries, are
not signaled during those intermediate passes, since it may happen that when
some of the values are predicted better, these errors will disappear. However
if assembler meets some illegal syntax construction or unknown instruction, it
always stops immediately. Also defining some label more than once causes such
error, because it makes the predictions groundless.

Only the messages created
with the \verb"display" directive during the last performed pass get actually
displayed. In case when the assembly has been stopped due to an error, these messages
may reflect the predicted values that are not yet resolved correctly.

The solution may sometimes not exist and in such cases the assembler will
never manage to make correct predictions -- for this reason there is a limit for
a number of passes, and when assembler reaches this limit, it stops and displays
the message that it is not able to generate the correct output. Consider the
following example:
\begin{verbatim}
    if ~ defined alpha
        alpha:
    end if
\end{verbatim}
The \verb"defined" operator gives the true value when the expression following it
could be calculated in this place, what in this case means that the \verb"alpha"
label is defined somewhere. But the above block causes this label to be defined
only when the value given by \verb"defined" operator is false, what leads to an
antynomy and makes it impossible to resolve such code. When processing the \verb"if"
directive assembler has to predict whether the \verb"alpha" label will be defined
somewhere (it wouldn't have to predict only if the label was already defined
earlier in this pass), and whatever the prediction is, the opposite always
happens. Thus the assembly will fail, unless the \verb"alpha" label is defined
somewhere in source preceding the above block of instructions -- in such case,
as it was already noted, the prediction is not needed and the block will just
get skipped.

The above sample might have been written as a try to define the label only
when it was not yet defined. It fails, because the \verb"defined" operator does
check whether the label is defined anywhere, and this includes the definition
inside this conditionally processed block. However adding some additional
condition may make it possible to get it resolved:
\begin{verbatim}
    if ~ defined alpha | defined @f
        alpha:
        @@:
    end if
\end{verbatim}
The \verb"@f" is always the same label as the nearest \verb"@@" symbol in the source
following it, so the above sample would mean the same if any unique name was
used instead of the anonymous label. When \verb"alpha" is not defined in any other
place in source, the only possible solution is when this block gets defined,
and this time this doesn't lead to the antynomy, because of the anonymous
label which makes this block self--establishing. To better understand this,
look at the blocks that has nothing more than this self-establishing:
\begin{verbatim}
    if defined @f
        @@:
    end if
\end{verbatim}
This is an example of source that may have more than one solution, as both
cases when this block gets processed or not are equally correct. Which one of
those two solutions we get depends on the algorithm on the assembler, in case
of flat assembler -- on the algorithm of predictions. Back to the previous
sample, when \verb"alpha" is not defined anywhere else, the condition for \verb"if" block
cannot be false, so we are left with only one possible solution, and we can
hope the assembler will arrive at it. On the other hand, when \verb"alpha" is
defined in some other place, we've got two possible solutions again, but one of
them causes \verb"alpha" to be defined twice, and such an error causes assembler to
abort the assembly immediately, as this is the kind of error that deeply
disturbs the process of resolving. So we can get such source either correctly
resolved or causing an error, and what we get may depend on the internal
choices made by the assembler.

However there are some facts about such choices that are certain. When
assembler has to check whether the given symbol is defined and it was already
defined in the current pass, no prediction is needed -- it was already noted
above. And when the given symbol has been defined never before, including all
the already finished passes, the assembler predicts it to be not defined.
Knowing this, we can expect that the simple self--establishing block shown
above will not be assembled at all and that the previous sample will resolve
correctly when \verb"alpha" is defined somewhere before our conditional block,
while it will itself define \verb"alpha" when it's not already defined earlier, thus
potentially causing the error because of double definition if the \verb"alpha" is
also defined somewhere later.

The \verb"used" operator may be expected to behave in a similar manner in
analogous cases, however any other kinds of predictions my not be so simple and
you should never rely on them this way.

The \verb"err" directive, usually used to stop the assembly when some condition is
met, stops the assembly immediately, regardless of whether the current pass
is final or intermediate. So even when the condition that caused this directive
to be interpreted is mispredicted and temporary, and would eventually disappear in the later
passes, the assembly is stopped anyway.

The \verb"assert" directive signalizes the error only if its expression is false
after all the symbols have been resolved. You can use \verb"assert 0" in place of
\verb"err" when you do not want to have assembly stopped during the intermediate
passes.


\section{Preprocessor directives}
\label{sec:preprocessor}
All preprocessor directives are processed before the main assembly process,
and therefore are not affected by the control directives. At this time also
all comments are stripped out.

\subsection{Including source files}
\index{INCLUDE}
\verb"include" directive includes the specified source file at the position
where it is used. It should be followed by the quoted name of file that
should be included, for example:
\begin{verbatim}
    include 'macros.inc'
\end{verbatim}
The whole included file is preprocessed before preprocessing the lines next
to the line containing the \verb"include" directive. There are no limits to
the number of included files as long as they fit in memory.

The quoted path can contain environment variables enclosed within \verb"%"
characters, they will be replaced with their values inside the
path, both the \verb"\" and \verb"/" characters are allowed as a
path separators. The file is first
searched for in the directory containing file which included it and when it is
not found there, the search is continued in the directories specified in the
environment variable called INCLUDE (the multiple paths separated with
semicolons can be defined there, they will be searched in the same order as
specified). If file was not found in any of these places, preprocessor looks
for it in the directory containing the main source file (the one specified in
command line). These rules concern also paths given with the \verb"file" directive.

\subsection{Symbolic constants}
\label{sec:symbolic_constants}
The symbolic constants are different from the numerical constants, before the
assembly process they are replaced with their values everywhere in source
lines after their definitions, and anything can become their values.

\index{EQU}
The definition of symbolic constant consists of name of the constant followed
by the \verb"equ" directive. Everything that follows this directive will
become the value of constant. If the value of symbolic constant contains
other symbolic constants, they are replaced with their values before
assigning this value to the new constant. For example:
\begin{verbatim}
    d equ dword
    NULL equ d 0
    d equ edx
\end{verbatim}
After these three definitions the value of \verb"NULL" constant is
\verb"dword 0" and the value of \verb"d" is \verb"edx". So, for example,
\verb"push NULL" will be assembled as \verb"push dword 0" and \verb"push d"
will be assembled as \verb"push edx". And if then the following line was put:
\begin{verbatim}
    d equ d,eax
\end{verbatim}
the \verb"d" constant would get the new value of \verb"edx,eax". This way the growing
lists of symbols can be defined.

\index{RESTORE}
\verb"restore" directive allows to get back previous value of redefined symbolic
constant. It should be followed by one more names of symbolic constants,
separated with commas. So \verb"restore d" after the above definitions will give
\verb"d" constant back the value \verb"edx", the second one will restore it to value
\verb"dword", and one more will revert \verb"d" to original meaning as if no such
constant was defined. If there was no constant defined of given name,
\verb"restore" will not cause an error, it will be just ignored.

Symbolic constant can be used to adjust the syntax of assembler to personal
preferences. For example the following set of definitions provides the handy
shortcuts for all the size operators:
\begin{verbatim}
    b equ byte
    w equ word
    d equ dword
    p equ pword
    f equ fword
    q equ qword
    t equ tword
    x equ dqword
    y equ qqword
\end{verbatim}

Because symbolic constant may also have an empty value, it can be used to
allow the syntax with \verb"offset" word before any address value:
\begin{verbatim}
    offset equ
\end{verbatim}
After this definition \verb"mov ax,offset char" will be valid construction
for copying the offset of \verb"char" variable into \verb"ax" register,
because \verb"offset" is replaced with an empty value, and therefore ignored.

\index{DEFINE}
The \verb"define" directive followed by the name of constant and then the value,
is the alternative way of defining symbolic constant. The only difference
between \verb"define" and \verb"equ" is that \verb"define" assigns the value as it is, it does
not replace the symbolic constants with their values inside it.

\index{FIX}
Symbolic constants can also be defined with the \verb"fix" directive, which has
the same syntax as \verb"equ", but defines constants of high priority -- they are
replaced with their symbolic values even before processing the preprocessor
directives and macroinstructions, the only exception is \verb"fix" directive
itself, which has the highest possible priority, so it allows redefinition of
constants defined this way.

The \verb"fix" directive can be used for syntax adjustments related to directives
of preprocessor, what cannot be done with \verb"equ" directive. For example:
\begin{verbatim}
    incl fix include
\end{verbatim}
defines a short name for \verb"include" directive, while the similar definition done
with \verb"equ" directive wouldn't give such result, as standard symbolic constants
are replaced with their values after searching the line for preprocessor
directives.


\subsection{Macroinstructions}
\index{MACRO}
\verb"macro" directive allows you to define your own complex instructions,
called macroinstructions, using which can greatly simplify the process of
programming. In its simplest form it's similar to symbolic constant
definition. For example the following definition defines a shortcut for the
\verb"test al,0xFF" instruction:
\begin{verbatim}
    macro tst {test al,0xFF}
\end{verbatim}
After the \verb"macro" directive there is a name of macroinstruction and then
its contents enclosed between the \verb"{" and \verb"}" characters. You can
use \verb"tst" instruction anywhere after this definition and it will be
assembled as \verb"test al,0xFF". Defining symbolic constant \verb"tst" of
that value would give the similar result, but the difference is that the name
of macroinstruction is recognized only as an instruction mnemonic. Also,
macroinstructions are replaced with corresponding code even before the
symbolic constants are replaced with their values. So if you define
macroinstruction and symbolic constant of the same name, and use this name as
an instruction mnemonic, it will be replaced with the contents of
macroinstruction, but it will be replaced with value if symbolic constant if
used somewhere inside the operands.

The definition of macroinstruction can consist of many lines, because
\verb"{" and \verb"}" characters don't have to be in the same line as
\verb"macro" directive. For example:
\begin{verbatim}
    macro stos0
     {
        xor al,al
        stosb
     }
\end{verbatim}
The macroinstruction \verb"stos0" will be replaced with these two assembly
instructions anywhere it's used.

Like instructions which needs some number of operands, the macroinstruction
can be defined to need some number of arguments separated with commas. The
names of needed argument should follow the name of macroinstruction in the
line of \verb"macro" directive and should be separated with commas if there
is more than one. Anywhere one of these names occurs in the contents of
macroinstruction, it will be replaced with corresponding value, provided when
the macroinstruction is used. Here is an example of a macroinstruction that
will do data alignment for binary output format:
\begin{verbatim}
    macro align value { rb (value-1)-($+value-1) mod value }
\end{verbatim}
When the \verb"align 4" instruction is found after this macroinstruction is
defined, it will be replaced with contents of this macroinstruction, and the
\verb"value" will there become 4, so the result will be
\verb%rb (4-1)-($+4-1) mod 4%.

If a macroinstruction is defined that uses an instruction with the same name
inside its definition, the previous meaning of this name is used. Useful
redefinition of macroinstructions can be done in that way, for example:
\begin{verbatim}
    macro mov op1,op2
     {
      if op1 in <ds,es,fs,gs,ss> & op2 in <cs,ds,es,fs,gs,ss>
        push  op2
        pop   op1
      else
        mov   op1,op2
      end if
     }
\end{verbatim}
This macroinstruction extends the syntax of \verb"mov" instruction, allowing
both operands to be segment registers. For example \verb"mov ds,es" will be
assembled as \verb"push es" and \verb"pop ds". In all other cases the
standard \verb"mov" instruction will be used. The syntax of this \verb"mov"
can be extended further by defining next macroinstruction of that name, which
will use the previous macroinstruction:
\begin{verbatim}
    macro mov op1,op2,op3
     {
      if op3 eq
        mov   op1,op2
      else
        mov   op1,op2
        mov   op2,op3
      end if
     }
\end{verbatim}
It allows \verb"mov" instruction to have three operands, but it can still
have two operands only, because when macroinstruction is given less arguments
than it needs, the rest of arguments will have empty values. When three
operands are given, this macroinstruction will become two macroinstructions
of the previous definition, so \verb"mov es,ds,dx" will be assembled as
\verb"push ds", \verb"pop es" and \verb"mov ds,dx".

By placing the \verb"*" after the name of argument you can mark the argument as
required -- preprocessor will not allow it to have an empty value. For example the
above macroinstruction could be declared as \verb"macro mov op1*,op2*,op3" to make
sure that first two arguments will always have to be given some non empty
values.

Alternatively, you can provide the default value for argument, by placing
the \verb"=" followed by value after the name of argument. Then if the argument
has an empty value provided, the default value will be used instead.

When it's needed to provide macroinstruction with argument that contains
some commas, such argument should be enclosed between \verb"<" and \verb">"
characters. If it contains more than one \verb"<" character, the same number
of \verb">" should be used to tell that the value of argument ends.

\index{PURGE}
\verb"purge" directive allows removing the last definition of specified
macroinstruction. It should be followed by one or more names of
macroinstructions, separated with commas. If such macroinstruction has not
been defined, you will not get any error. For example after having the syntax of
\verb"mov" extended with the macroinstructions defined above, you can disable
syntax with three operands back by using \verb"purge mov" directive. Next
\verb"purge mov" will disable also syntax for two operands being segment
registers, and all the next such directives will do nothing.

If after the \verb"macro" directive you enclose some group of arguments'
names in square brackets, it will allow giving more values for this group of
arguments when using that macroinstruction. Any more argument given after the
last argument of such group will begin the new group and will become the
first argument of it. That's why after closing the square bracket no more
argument names can follow. The contents of macroinstruction will be processed
for each such group of arguments separately. The simplest example is to
enclose one argument name in square brackets:
\begin{verbatim}
    macro stoschar [char]
     {
        mov al,char
        stosb
     }
\end{verbatim}
This macroinstruction accepts unlimited number of arguments, and each one
will be processed into these two instructions separately. For example
\verb"stoschar 1,2,3" will be assembled as the following instructions:
\begin{verbatim}
    mov al,1
    stosb
    mov al,2
    stosb
    mov al,3
    stosb
\end{verbatim}

\index{LOCAL}
There are some special directives available only inside the definitions of
macroinstructions. \verb"local" directive defines local names, which will be
replaced with unique values each time the macroinstruction is used. It should
be followed by names separated with commas. If the name given as parameter to \verb"local" directive begins with a dot or two
dots, the unique labels generated by each evaluation of macroinstruction will
have the same properties. This directive is usually needed
for the constants or labels that macroinstruction defines and uses
internally.
For example:
\begin{verbatim}
    macro movstr
     {
        local move
      move:
        lodsb
        stosb
        test al,al
        jnz move
     }
\end{verbatim}
Each time this macroinstruction is used, \verb"move" will become other
unique name in its instructions, so you will not get an error you normally get
when some label is defined more than once.

\index{FORWARD}\index{REVERSE}\index{COMMON}
\verb"forward", \verb"reverse" and \verb"common" directives divide
macroinstruction into blocks, each one processed after the processing of
previous is finished. They differ in behavior only if macroinstruction allows
multiple groups of arguments. Block of instructions that follows
\verb"forward" directive is processed for each group of arguments, from
first to last -- exactly like the default block (not preceded by any of these
directives). Block that follows \verb"reverse" directive is processed
for each group of argument in reverse order -- from last to first. Block that
follows \verb"common" directive is processed only once, commonly for all
groups of arguments. Local name defined in one of the blocks is available in
all the following blocks when processing the same group of arguments as when
it was defined, and when it is defined in common block it is available in all
the following blocks not depending on which group of arguments is processed.

Here is an example of macroinstruction that will create the table of
addresses to strings followed by these strings:
\begin{verbatim}
    macro strtbl name,[string]
     {
      common
        label name dword
      forward
        local label
        dd label
      forward
        label db string,0
     }
\end{verbatim}
First argument given to this macroinstruction will become the label for table
of addresses, next arguments should be the strings. First block is processed
only once and defines the label, second block for each string declares its
local name and defines the table entry holding the address to that string.
Third block defines the data of each string with the corresponding label.

The directive starting the block in macroinstruction can be followed by the
first instruction of this block in the same line, like in the following
example:
\begin{verbatim}
    macro stdcall proc,[arg]
     {
      reverse push arg
      common call proc
     }
\end{verbatim}
This macroinstruction can be used for calling the procedures using STDCALL
convention, which has all the arguments pushed on stack in the reverse order. For example
\verb"stdcall foo,1,2,3" will be assembled as:
\begin{verbatim}
    push 3
    push 2
    push 1
    call foo
\end{verbatim}

If some name inside macroinstruction has multiple values (it is either one of
the arguments enclosed in square brackets or local name defined in the block
following \verb"forward" or \verb"reverse" directive) and is used in block
following the \verb"common" directive, it will be replaced with all of its
values, separated with commas. For example the following macroinstruction
will pass all of the additional arguments to the previously defined
\verb"stdcall" macroinstruction:
\begin{verbatim}
    macro invoke proc,[arg]
     { common stdcall [proc],arg }
\end{verbatim}
It can be used to call indirectly (by the pointer stored in memory) the
procedure using STDCALL convention.

Inside macroinstruction also special operator \verb"#" can be used. This
operator causes two names to be concatenated into one name. It can be useful,
because it's done after the arguments and local names are replaced with their
values. The following macroinstruction will generate the conditional jump
according to the \verb"cond" argument:
\begin{verbatim}
    macro jif op1,cond,op2,label
     {
        cmp op1,op2
        j#cond label
     }
\end{verbatim}
For example \verb"jif ax,ae,10h,exit" will be assembled as \verb"cmp ax,10h"
and \verb"jae exit" instructions.

The \verb"#" operator can be also used to concatenate two quoted strings into one.
Also conversion of name into a quoted string is possible, with the \verb"`" operator,
which likewise can be used inside the macroinstruction. It converts the name
that follows it into a quoted string -- but note, that when it is followed by
a macro argument which is being replaced with value containing more than one
symbol, only the first of them will be converted, as the \verb"`" operator converts
only one symbol that immediately follows it. Here's an example of utilizing
those two features:
\begin{verbatim}
    macro label name
     {
        label name
        if ~ used name
          display `name # " is defined but not used.",13,10
        end if
     }
\end{verbatim}
When label defined with such macro is not used in the source, macro will warn
you with the message, informing to which label it applies.

To make macroinstruction behaving differently when some of the arguments are
of some special type, for example a quoted strings, you can use \verb"eqtype"
comparison operator. Here's an example of utilizing it to distinguish a
quoted string from an other argument.
\begin{verbatim}
    macro message arg
     {
      if arg eqtype ""
        local str
        jmp   @f
        str   db arg,0Dh,0Ah,24h
        @@:
        mov   dx,str
      else
        mov   dx,arg
      end if
        mov   ah,9
        int   21h
     }
\end{verbatim}
The above macro is designed for displaying messages in DOS programs. When the
argument of this macro is some number, label, or variable, the string from
that address is displayed, but when the argument is a quoted string, the
created code will display that string followed by the carriage return and
line feed.

It is also possible to put a declaration of macroinstruction
inside another macroinstruction, so one macro can define another,
but there is a problem with such definitions caused by the fact,
that \verb"}" character cannot occur inside the macroinstruction,
as it always means the end of definition. To
overcome this problem, the escaping of symbols inside macroinstruction can be
used. This is done by placing one or more
backslashes in front of any other symbol (even the special
character). Preprocessor sees such sequence as a single symbol,
but each time it meets such symbol during the macroinstruction
processing, it cuts the backslash character from the front of it.
For example \verb"\}" is treated as single symbol, but during
processing of the macroinstruction it becomes the \verb"}" symbol.
This allows to put one definition of macroinstruction inside
another:
\begin{verbatim}
    macro ext instr
     {
      macro instr op1,op2,op3
       \{
        if op3 eq
          instr op1,op2
        else
          instr op1,op2
          instr op2,op3
        end if
       \}
     }

    ext add
    ext sub
\end{verbatim}
The macro \verb"ext" is defined correctly, but when it is used,
the \verb"\{" and \verb"\}" become the \verb"{" and \verb"}"
symbols. So when the \verb"ext add" is processed, the contents of
macro becomes valid definition of a macroinstruction and this way
the \verb"add" macro becomes defined. In the same way \verb"ext sub" defines
the \verb"sub" macro. The use of \verb"\{" symbol wasn't
really necessary here, but is done this way to make the definition
more clear.

If some directives specific to macroinstructions, like \verb"local" or \verb"common"
are needed inside some macro embedded this way, they can be
escaped in the same way. Escaping the symbol with more than one
backslash is also allowed, which allows multiple levels of nesting
the macroinstruction definitions.

The another technique for defining one macroinstruction by another is to
use the \verb"fix" directive, which becomes useful when some macroinstruction only
begins the definition of another one, without closing it. For example:
\begin{verbatim}
    macro tmacro [params]
     {
      common macro params {
     }

    MACRO fix tmacro
    ENDM fix }
\end{verbatim}
defines an alternative syntax for defining macroinstructions, which looks like:
\begin{verbatim}
    MACRO stoschar char
        mov al,char
        stosb
    ENDM
\end{verbatim}
Note that symbol that has such customized definition must be defined with \verb"fix"
directive, because only the prioritized symbolic constants are processed before
the preprocessor looks for the \verb"}" character while defining the macro. This
might be a problem if one needed to perform some additional tasks one the end
of such definition, but there is one more feature which helps in such cases.
Namely it is possible to put any directive, instruction or  macroinstruction
just after the \verb"}" character that ends the macroinstruction and it will be
processed in the same way as if it was put in the next line.

\subsection{Structures}
\index{STRUC}
\verb"struc" directive is a special variant of \verb"macro" directive that is
used to define data structures. Macroinstruction defined using the
\verb"struc" directive must be preceded by a label (like the data definition
directive) when it's used. This label will be also attached at the beginning
of every name starting with dot in the contents of macroinstruction. The
macroinstruction defined using the \verb"struc" directive can have the same
name as some other macroinstruction defined using the \verb"macro" directive,
structure macroinstruction will not prevent the standard macroinstruction from being
processed when there is no label before it and vice versa. All the rules and features
concerning standard macroinstructions apply to structure macroinstructions.

Here is the sample of structure macroinstruction:
\begin{verbatim}
    struc point x,y
     {
        .x dw x
        .y dw y
     }
\end{verbatim}
For example \verb"my point 7,11" will define structure labeled \verb"my",
consisting of two variables: \verb"my.x" with value 7 and \verb"my.y" with
value 11.

If somewhere inside the definition of structure the name consisting of a
single dot it found, it is replaced by the name of the label for the given
instance of structure and this label will not be defined automatically in
such case, allowing to completely customize the definition. The following
example utilizes this feature to extend the data definition directive \verb"db"
with ability to calculate the size of defined data:
\begin{verbatim}
    struc db [data]
     {
       common
        . db data
        .size = $ - .
     }
\end{verbatim}
With such definition \verb"msg db 'Hello!',13,10" will define also \verb"msg.size"
constant, equal to the size of defined data in bytes.

Defining data structures addressed by registers or absolute values should be
done using the \verb"virtual" directive with structure macroinstruction
(see \ref{sec:other}).

\index{RESTRUC}
\verb"restruc" directive removes the last definition of the structure, just like
\verb"purge" does with macroinstructions and \verb"restore" with symbolic constants.
It also has the same syntax -- should be followed by one or more names of
structure macroinstructions, separated with commas.

\subsection{Repeating macroinstructions}
\index{REPT}
The \verb"rept" directive is a special kind of macroinstruction, which makes given
amount of duplicates of the block enclosed with braces. The basic syntax is
\verb"rept" directive followed by number and then block of source enclosed between
the \verb"{" and \verb"}" characters. The simplest example:
\begin{verbatim}
    rept 5 { in al,dx }
\end{verbatim}
will make five duplicates of the \verb"in al,dx" line. The block of instructions
is defined in the same way as for the standard macroinstruction and any
special operators and directives which can be used only inside
macroinstructions are also allowed here. When the given count is zero, the
block is simply skipped, as if you defined macroinstruction but never used
it. The number of repetitions can be followed by the name of counter symbol, which will get replaced
symbolically with the number of duplicate currently generated. So this:
\begin{verbatim}
    rept 3 counter
     {
        byte#counter db counter
     }
\end{verbatim}
will generate lines:
\begin{verbatim}
    byte1 db 1
    byte2 db 2
    byte3 db 3
\end{verbatim}
The repetition mechanism applied to \verb"rept" blocks is the same as the one used
to process multiple groups of arguments for macroinstructions, so directives
like \verb"forward", \verb"common" and \verb"reverse" can be used in their usual meaning.
Thus such macroinstruction:
\begin{verbatim}
    rept 7 num { reverse display `num }
\end{verbatim}
will display digits from 7 to 1 as text. The \verb"local" directive behaves in the
same way as inside macroinstruction with multiple groups of arguments, so:
\begin{verbatim}
    rept 21
     {
       local label
       label: loop label
     }
\end{verbatim}
will generate unique label for each duplicate.

The counter symbol by default counts from 1, but you can declare different
base value by placing the number preceded by colon immediately after the name
of counter. For example:
\begin{verbatim}
    rept 8 n:0 { pxor xmm#n,xmm#n }
\end{verbatim}
will generate code which will clear the contents of eight SSE registers.
You can define multiple counters separated with commas, and each one can have
different base.

The number of repetitions and the base values for counters can be specified
using the numerical expressions with operator rules identical as in the case
of assembler. However each value used in such expression must either be a
directly specified number, or a symbolic constant with value also being an
expression that can be calculated by preprocessor (in such case the value
of expression associated with symbolic constant is calculated first, and then
substituted into the outer expression in place of that constant). If you need
repetitions based on values that can only be calculated at assembly time, use
one of the code repeating directives that are processed by assembler, see
section \ref{sec:repeating}.

\index{IRP}
The \verb"irp" directive iterates the single argument through the given list of
parameters. The syntax is \verb"irp" followed by the argument name, then the comma
and then the list of parameters. The parameters are specified in the same
way like in the invocation of standard macroinstruction, so they have to be
separated with commas and each one can be enclosed with the \verb"<" and \verb">"
characters. Also the name of argument may be followed by \verb"*" to mark that it
cannot get an empty value. Such block:
\begin{verbatim}
   irp value, 2,3,5
    { db value }
\end{verbatim}
will generate lines:
\begin{verbatim}
   db 2
   db 3
   db 5
\end{verbatim}
\index{IRPS}
The \verb"irps" directive iterates through the given list of symbols, it should
be followed by the argument name, then the comma and then the sequence of any
symbols. Each symbol in this sequence, no matter whether it is the name
symbol, symbol character or quoted string, becomes an argument value for one
iteration. If there are no symbols following the comma, no iteration is done
at all. This example:
\begin{verbatim}
   irps reg, al bx ecx
    { xor reg,reg }
\end{verbatim}
will generate lines:
\begin{verbatim}
   xor al,al
   xor bx,bx
   xor ecx,ecx
\end{verbatim}
The blocks defined by the \verb"irp" and \verb"irps" directives are also processed in
the same way as any macroinstructions, so operators and directives specific
to macroinstructions may be freely used also in this case.


\subsection{Conditional preprocessing}
\label{sec:conditional_preprocessing}
\index{MATCH}
\verb"match" directive causes some block of source to be preprocessed and passed
to assembler only when the given sequence of symbols matches the specified
pattern. The pattern comes first, ended with comma, then the symbols
that have to be matched with the pattern, and finally the block of
source, enclosed within braces as macroinstruction.

There are the few rules for building the expression for matching, first is
that any of symbol characters and any quoted string should be matched exactly as is. In this example:
\begin{verbatim}
    match +,+ { include 'first.inc' }
    match +,- { include 'second.inc' }
\end{verbatim}
the first file will get included, since \verb"+" after comma matches the \verb"+" in
pattern, and the second file will not be included, since there is no match.

To match any other symbol literally, it has to be preceded by \verb"=" character
in the pattern. Also to match the \verb"=" character itself, or the comma, the
\verb"==" and \verb"=," constructions have to be used. For example the \verb"=a==" pattern
will match the \verb"a=" sequence.

If some name symbol is placed in the pattern, it matches any sequence
consisting of at least one symbol and then this name is replaced with the
matched sequence everywhere inside the following block, analogously to the
parameters of macroinstruction. For instance:
\begin{verbatim}
    match a-b, 0-7
     { dw a,b-a }
\end{verbatim}
will generate the \verb"dw 0,7-0" instruction. Each name is always matched with
as few symbols as possible, leaving the rest for the following ones, so in
this case:
\begin{verbatim}
    match a b, 1+2+3 { db a }
\end{verbatim}
the \verb"a" name will match the \verb"1" symbol, leaving the \verb"+2+3" sequence to be
matched with \verb"b". But in this case:
\begin{verbatim}
    match a b, 1 { db a }
\end{verbatim}
there will be nothing left for \verb"b" to match, so the block will not get processed
at all.

The block of source defined by match is processed in the same way as any
macroinstruction, so any operators specific to macroinstructions can be used
also in this case.

What makes "match" directive more useful is the fact, that it replaces the
symbolic constants with their values in the matched sequence of symbols (that
is everywhere after comma up to the beginning of the source block) before
performing the match. Thanks to this it can be used for example to process
some block of source under the condition that some symbolic constant has the
given value, like:
\begin{verbatim}
    match =TRUE, DEBUG { include 'debug.inc' }
\end{verbatim}
which will include the file only when the symbolic constant \verb"DEBUG" was
defined with value \verb"TRUE".

\subsection{Order of processing}
When combining various features of the preprocessor, it's important to know
the order in which they are processed. As it was already noted, the highest
priority has the \verb"fix" directive and the replacements defined with it. This
is done completely before doing any other preprocessing, therefore this
piece of source:
\begin{verbatim}
    V fix {
      macro empty
       V
    V fix }
       V
\end{verbatim}
becomes a valid definition of an empty macroinstruction. It can be interpreted
that the \verb"fix" directive and prioritized symbolic constants are processed in
a separate stage, and all other preprocessing is done after on the resulting
source.

The standard preprocessing that comes after, on each line begins with
recognition of the first symbol. It starts with checking for the preprocessor
directives, and when none of them is detected, preprocessor checks whether the
first symbol is macroinstruction. If no macroinstruction is found, it moves
to the second symbol of line, and again begins with checking for directives,
which in this case is only the \verb"equ" directive, as this is the only one that
occurs as the second symbol in line. If there is no directive, the second
symbol is checked for the case of structure macroinstruction and when none
of those checks gives the positive result, the symbolic constants are replaced
with their values and such line is passed to the assembler.

To see it on the example, assume that there is defined the macroinstruction
called \verb"foo" and the structure macroinstruction called \verb"bar". Those lines:
\begin{verbatim}
    foo equ
    foo bar
\end{verbatim}
would be then both interpreted as invocations of macroinstruction \verb"foo", since
the meaning of the first symbol overrides the meaning of second one.

When the macroinstruction generates the new lines from its
definition block, in every line it first scans for
macroinstruction directives, and interpretes them accordingly. All
the other content in the definition block is used to brew the new
lines, replacing the parameters with their values and then
processing the symbol escaping and \verb"#" and \verb"`"
operators. The conversion operator has the higher priority than
concatenation and if any of them operates on the escaped symbol,
the escaping is cancelled before finishing the operation. After
this is completed, the newly generated line goes through the
standard preprocessing, as described above.

Though the symbolic constants are usually only replaced in the lines, where
no preprocessor directives nor macroinstructions has been found, there are some
special cases where those replacements are performed in the parts of lines
containing directives. First one is the definition of symbolic constant, where
the replacements are done everywhere after the \verb"equ" keyword and the resulting
value is then assigned to the new constant (see \ref{sec:symbolic_constants}).
The second such case is the \verb"match" directive, where the replacements are done in the symbols
following comma before matching them with pattern. These features can be used
for example to maintain the lists, like this set of definitions:
\begin{verbatim}
    list equ

    macro append item
     {
       match any, list \{ list equ list,item \}
       match , list \{ list equ item \}
     }
\end{verbatim}
The \verb"list" constant is here initialized with empty value, and the \verb"append"
macroinstruction can be used to add the new items into this list, separating
them with commas. The first match in this macroinstruction occurs only when
the value of list is not empty (see \ref{sec:conditional_preprocessing}), in such case the new value for the
list is the previous one with the comma and the new item appended at the end.
The second match happens only when the list is still empty, and in such case
the list is defined to contain just the new item. So starting with the empty
list, the \verb"append 1" would define \verb"list equ 1" and the \verb"append 2" following it
would define \verb"list equ 1,2". One might then need to use this list as the
parameters to some macroinstruction. But it cannot be done directly -- if \verb"foo"
is the macroinstruction, then \verb"foo list" would just pass the \verb"list" symbol
as a parameter to macro, since symbolic constants are not unrolled at this
stage. For this purpose again \verb"match" directive comes in handy:
\begin{verbatim}
    match params, list { foo params }
\end{verbatim}
The value of \verb"list", if it's not empty, matches the \verb"params" keyword, which is
then replaced with matched value when generating the new lines defined by the
block enclosed with braces. So if the \verb"list" had value \verb"1,2", the above line
would generate the line containing \verb"foo 1,2", which would then go through the
standard preprocessing.

The other special case is in the parameters of \verb"rept" directive. The amount
of repetitions and the base value for counter can be specified using
numerical expressions, and if there is a symbolic constant with non--numerical
name used in such an expression, preprocessor tries to evaluate its value as a numerical expression
and if succeeds, it replaces the symbolic constant with the result of that
calculation and continues to evaluate the primary expression. If the
expression inside that symbolic constants also contains some symbolic
constants, preprocessor will try to calculate all the needed values
recursively.

This allows to perform some calculations at the time of preprocessing, as
long as all the values used are the numbers known at the preprocessing stage.
A single repetition with \verb"rept" can be used for the sole purpose of
calculating some value, like in this example:
\begin{verbatim}
    define a b+4
    define b 3
    rept 1 result:a*b+2 { define c result }
\end{verbatim}
To compute the base value for \verb"result" counter, preprocessor replaces the \verb"b"
with its value and recursively calculates the value of \verb"a", obtaining 7 as
the result, then it calculates the main expression with the result being 23.
The \verb"c" then gets defined with the first value of counter (because the block
is processed just one time), which is the result of the computation, so the
value of \verb"c" is simple \verb"23" symbol. Note that if \verb"b" is later redefined with
some other numerical value, the next time and expression containing \verb"a" is
calculated, the value of \verb"a" will reflect the new value of \verb"b", because the
symbolic constant contains just the text of the expression.

There is one more special case -- when preprocessor goes to checking the
second symbol in the line and it happens to be the colon character (what is
then interpreted by assembler as definition of a label), it stops in this
place and finishes the preprocessing of the first symbol (so if it's the
symbolic constant it gets unrolled) and if it still appears to be the label,
it performs the standard preprocessing starting from the place after the
label. This allows to place preprocessor directives and macroinstructions
after the labels, analogously to the instructions and directives processed
by assembler, like:
\begin{verbatim}
    start: include 'start.inc'
\end{verbatim}
However if the label becomes broken during preprocessing (for example when
it is the symbolic constant with empty value), only replacing of the symbolic
constants is continued for the rest of line.

It should be remembered, that the jobs performed by preprocessor are the
preliminary operations on the texts symbols, that are done in a simple
single pass before the main process of assembly. The text that is the
result of preprocessing is passed to assembler, and it then does its
multiple passes on it. Thus the control directives, which are recognized and
processed only by the assembler -- as they are dependent on the numerical
values that may even vary between passes -- are not recognized in any way by
the preprocessor and have no effect on the preprocessing. Consider this
example source:
\begin{verbatim}
    if 0
    a = 1
    b equ 2
    end if
    dd b
\end{verbatim}
When it is preprocessed, they only directive that is recognized by the
preprocessor is the \verb"equ", which defines symbolic constant \verb"b", so later
in the source the \verb"b" symbol is replaced with the value \verb"2". Except for this
replacement, the other lines are passes unchanged to the assembler. So
after preprocessing the above source becomes:
\begin{verbatim}
    if 0
    a = 1
    end if
    dd 2
\end{verbatim}
Now when assembler processes it, the condition for the \verb"if" is false, and
the \verb"a" constant doesn't get defined. However symbolic constant \verb"b" was
processed normally, even though its definition was put just next to the one
of \verb"a". So because of the possible confusion you should be very careful
every time when mixing the features of preprocessor and assembler - in such
cases it is important to realize what the source will become after the
preprocessing, and thus what the assembler will see and do its multiple passes
on.

\section{Formatter directives}
\label{sec:formatter}
\index{FORMAT}
These directives are actually also a kind of control directives, with the
purpose of controlling the format of generated code.

\verb"format" directive followed by the format identifier allows to select
the output format. This directive should be put at the beginning of the
source. Default output format is a flat binary file, it can also be selected
by using \verb"format binary" directive.
This directive can be followed by the \verb"as" keyword
and the quoted string specifying the default file extension for the output
file. Unless the output file name was specified from the command line,
assembler will use this extension when generating the output file.

\index{USE16, USE32, USE64}
\verb"use16" and \verb"use32" directives force the assembler to generate 16--bit or
32--bit code, omitting the default setting for selected output format. \verb"use64"
enables generating the code for the long mode of x86--64 processors.

Below are described different output formats with the directives
specific to these formats.

\subsection{MZ executable}
To select the MZ output format, use \verb"format MZ" directive. The default
code setting for this format is 16--bit.

\index{SEGMENT}
\verb"segment" directive defines a new segment, it should be followed by
label, which value will be the number of defined segment, optionally
\verb"use16" or \verb"use32" word can follow to specify whether code in this
segment should be 16--bit or 32--bit. The origin of segment is aligned to
paragraph (16 bytes). All the labels defined then will have values relative
to the beginning of this segment.

\index{ENTRY}
\verb"entry" directive sets the entry point for MZ executable, it should be
followed by the far address (name of segment, colon and the offset inside
segment) of desired entry point.

\index{STACK}
\verb"stack" directive sets up the stack for MZ executable. It can be
followed by numerical expression specifying the size of stack to be created
automatically or by the far address of initial stack frame when you want to
set up the stack manually. When no stack is defined, the stack of default
size 4096 bytes will be created.

\index{HEAP}
\verb"heap" directive should be followed by a 16--bit value defining maximum
size of additional heap in paragraphs (this is heap in addition to stack and
undefined data). Use \verb"heap 0" to always allocate only memory program
really needs. Default size of heap is 65535.

\subsection{Portable Executable}
To select the Portable Executable output format, use \verb"format PE" directive,
it can be followed by additional format settings: first the target subsystem
setting, which can be \verb"console" or \verb"GUI" for Windows applications, \verb"native"
for Windows drivers, \verb"EFI", \verb"EFIboot" or \verb"EFIruntime" for the UEFI, it may be
followed by the minimum version of system that the executable is targeted to
(specified in form of floating-point value). Optional \verb"DLL" and \verb"WDM" keywords
mark the output file as a dynamic link library and WDM driver respectively,
and the \verb"large" keyword marks the executable as able to handle addresses
larger than 2 GB.

After those settings can follow the \verb"at" operator and the numerical expression
specifying the base of PE image and then optionally \verb"on" operator followed by
the quoted string containing file name selects custom MZ stub for PE program
(when specified file is not a MZ executable, it is treated as a flat binary
executable file and converted into MZ format). The default code setting for
this format is 32--bit. The example of fully featured PE format declaration:
\begin{verbatim}
    format PE GUI 4.0 DLL at 7000000h on 'stub.exe'
\end{verbatim}

To create PE file for the x86--64 architecture, use \verb"PE64" keyword instead of
\verb"PE" in the format declaration, in such case the long mode code is generated
by default.

\index{SECTION}
\verb"section" directive defines a new section, it should be
followed by quoted string defining the name of section, then one
or more section flags can follow. Available flags are:
\verb"code", \verb"data", \verb"readable", \verb"writeable",
\verb"executable", \verb"shareable", \verb"discardable",
\verb"notpageable". The origin of section is aligned to page (4096
bytes). Example declaration of PE section:
\begin{verbatim}
    section '.text' code readable executable
\end{verbatim}
Among with flags also on of special PE data identifiers can be
specified to mark the whole section as a special data, possible
identifiers are \verb"export", \verb"import", \verb"resource" and
\verb"fixups". If the section is marked to contain fixups, they
are generated automatically and no more data needs to be defined
in this section. Also resource data can be generated automatically
from the resource file, it can be achieved by writing the
\verb"from" operator and quoted file name after the
\verb"resource" identifier. Below are the examples of sections
containing some special PE data:
\begin{verbatim}
    section '.reloc' data readable discardable fixups
    section '.rsrc' data readable resource from 'my.res'
\end{verbatim}

\index{ENTRY}
\verb"entry" directive sets the entry point for Portable Executable, the
value of entry point should follow.

\index{STACK}
\verb"stack" directive sets up the size of stack for Portable Executable,
value of stack reserve size should follow, optionally value of stack commit
separated with comma can follow. When stack is not defined, it's set by
default to size of 4096 bytes.

\index{HEAP}
\verb"heap" directive chooses the size of heap for Portable Executable, value
of heap reserve size should follow, optionally value of heap commit separated
with comma can follow. When no heap is defined, it is set by default to size
of 65536 bytes, when size of heap commit is unspecified, it is by default set
to zero.

\index{DATA}\index{END}
\verb"data" directive begins the definition of special PE data, it should be
followed by one of the data identifiers (\verb"export", \verb"import",
\verb"resource" or \verb"fixups") or by the number of data entry in PE
header. The data should be defined in next lines, ended with \verb"end data"
directive. When fixups data definition is chosen, they are generated
automatically and no more data needs to be defined there.
The same applies to the resource data when the \verb"resource"
identifier is followed by \verb"from" operator and quoted file name --
in such case data is  taken from the given resource file.

The \verb"rva" operator can be used inside the numerical expressions to obtain
the RVA of the item addressed by the value it is applied to, that is the
offset relative to the base of PE image.

\subsection{Common Object File Format}
To select Common Object File Format, use \verb"format COFF" or \verb"format MS COFF"
directive, depending whether you want to create classic (DJGPP) or Microsoft's
variant of COFF file. The default code setting for this format is 32-bit. To
create the file in Microsoft's COFF format for the x86-64 architecture, use
\verb"format MS64 COFF" setting, in such case long mode code is generated by
default.

\index{SECTION}
\verb"section" directive defines a new section, it should be followed by
quoted string defining the name of section, then one or more section flags
can follow. Section flags available for both COFF variants are \verb"code" and \verb"data",
while flags \verb"readable", \verb"writeable", \verb"executable", \verb"shareable", \verb"discardable",
\verb"notpageable", \verb"linkremove" and \verb"linkinfo" are available only with
Microsoft's COFF variant.

By default section is aligned
to double word (four bytes), in case of Microsoft COFF variant other alignment
can be specified by providing the \verb"align" operator followed by alignment value
(any power of two up to 8192) among the section flags.

\index{EXTRN}
\verb"extrn" directive defines the external symbol, it should be
followed by the name of symbol and optionally the size operator
specifying the size of data labeled by this symbol. The name of
symbol can be also preceded by quoted string containing name of
the external symbol and the \verb"as" operator. Some example
declarations of external symbols:
\begin{verbatim}
    extrn exit
    extrn '__imp__MessageBoxA@16' as MessageBox:dword
\end{verbatim}

\index{PUBLIC}
\verb"public" directive declares the existing symbol as public, it
should be followed by the name of symbol, optionally it can be
followed by the \verb"as" operator and the quoted string
containing name under which symbol should be available as public.
Some examples of public symbols declarations:
\begin{verbatim}
    public main
    public start as '_start'
\end{verbatim}
Additionally, with COFF format it's possible to specify exported symbol as
static, it's done by preceding the name of symbol with the \verb"static" keyword.

When using the Microsoft's COFF format, the \verb"rva" operator can be used
inside the numerical expressions to obtain the RVA of the item addressed by the
value it is applied to.


\subsection{Executable and Linkable Format}
To select ELF output format, use \verb"format ELF" directive. The default code
setting for this format is 32--bit. To create ELF file for the x86--64
architecture, use \verb"format ELF64" directive, in such case the long mode code is
generated by default.

\index{SECTION}
\verb"section" directive defines a new section, it should be followed by quoted
string defining the name of section, then can follow one or both of the
\verb"executable" and \verb"writeable" flags, optionally also \verb"align" operator
followed by the number specifying the alignment of section (it has to be the power of
two), if no alignment is specified, the default value is used, which is 4 or 8,
depending on which format variant has been chosen.

\index{EXTRN}\index{PUBLIC}
\verb"extrn" and \verb"public" directives have the same meaning and syntax as
when the COFF output format is selected (described in previous section).

The  \verb"rva" operator can be used also in the case of this format (however not
when target architecture is x86--64), it converts the address into the offset
relative to the GOT table, so it may be useful to create position-independent
code. There's also a special \verb"plt" operator, which allows to call the external
functions through the Procedure Linkage Table. You can even create an alias
for external function that will make it always be called through PLT, with
the code like:
\begin{verbatim}
    extrn 'printf' as _printf
    printf = PLT _printf
\end{verbatim}

To create executable file, follow the format choice directive with the \verb"executable" keyword
and optionally the number specifying the brand of the target operating system
(for example value 3 would mark the executable for Linux systems).
With this format selected it is allowed to use \verb"entry" directive followed by the value to set as entry
point of program. On the other hand it makes \verb"extrn" and
\verb"public" directives unavailable, and instead of \verb"section" there should be the
\verb"segment" directive used, followed by one or
more segment permission flags and optionally a marker of special ELF
executable segment, which can be \verb"interpreter", \verb"dynamic" or \verb"note".
The origin of segment is aligned to page (4096 bytes), and available
permission flags are: \verb"readable", \verb"writeable" and \verb"executable".


\chapter{Windows programming}
With the Windows version of flat assembler comes the package of
standard includes designed to help in writing the programs for
Windows environment.

The includes package contains the headers for 32--bit and 64--bit Windows
programming in the root folder and the specialized includes in the
subfolders. In general, the headers include the required
specialized files for you, though sometimes you might prefer to
include some of the macroinstruction packages yourself (since few
of them are not included by some or even all of the headers).

There are six headers for 32--bit Windows that you can choose from, with names
starting with \verb"win32" followed by either a letter \verb"a"
for using the ASCII encoding, or a letter \verb"w" for the
WideChar encoding. The \verb"win32a.inc" and \verb"win32w.inc" are
the basic headers, the \verb"win32ax.inc" and \verb"win32wx.inc"
are the extended headers, they provide more advanced
macroinstructions, those extensions will be discussed separately.
Finally the \verb"win32axp.inc" and \verb"win32wxp.inc" are the
same extended headers with enabled feature of checking the count
of parameters in procedure calls.

There are analogous six packages for the 64--bit Windows, with
names starting with \verb"win64". They provide in general the
same functionality as the ones for 32--bit Windows, with just a few
differences explained later.

You can include the headers any way you prefer, by providing the
full path or using the custom environment variable, but the
simplest method is to define the \verb"INCLUDE" environment
variable properly pointing to the directory containing headers and
then include them just like:
\begin{verbatim}
  include 'win32a.inc'
\end{verbatim}

It's important to note that all macroinstructions, as opposed to
internal directives of flat assembler, are case sensitive and the
lower case is used for the most of them. If you'd prefer to use
the other case than default, you should do the appropriate
adjustments with \verb"fix" directive.

\section{Basic headers}
The basic headers \verb"win32a.inc", \verb"win32w.inc",
\verb"win64a.inc" and \verb"win64w.inc" include
the declarations of Windows equates and structures and provide the
standard set of macroinstructions.

\subsection{Structures}
All headers enable the \verb"struct" macroinstruction, which
allows to define structures in a way more similar to other
assemblers than the \verb"struc" directive. The definition of
structure should be started with \verb"struct" macroinstruction
followed by the name, and ended with \verb"ends" macroinstruction.
In lines between only data definition directives are allowed, with
labels being the pure names for the fields of structure:
\begin{verbatim}
  struct POINT
    x dd ?
    y dd ?
  ends
\end{verbatim}
With such definition this line:
\begin{verbatim}
  point1 POINT
\end{verbatim}
will declare the \verb"point1" structure with the \verb"point1.x"
and \verb"point1.y" fields, giving them the default values -- the
same ones as provided in the definition of structure (in this case
the defaults are both uninitialized values). But declaration of
structure also accepts the parameters, in the same count as the
number of fields in the structure, and those parameters, when
specified, override the default values for fields. For example:
\begin{verbatim}
  point2 POINT 10,20
\end{verbatim}
initializes the \verb"point2.x" field with value 10, and the
\verb"point2.y" with value 20.

The \verb"struct" macro not only enables to declare the structures
of given type, but also defines labels for offsets of fields
inside the structure and constants for sized of every field and
the whole structure. For example the above definition of
\verb"POINT" structure defines the \verb"POINT.x" and
\verb"POINT.y" labels to be the offsets of fields inside the
structure, and \verb"sizeof.POINT.x", \verb"sizeof.POINT.y" and
\verb"sizeof.POINT" as sizes of the corresponding fields and of
the whole structure. The offset labels may be used for accessing
the structures addressed indirectly, like:
\begin{verbatim}
  mov eax,[ebx+POINT.x]
\end{verbatim}
when the \verb"ebx" register contains the pointer to \verb"POINT"
structure. Note that field size checking will be performed with
such accessing as well.

The structures itself are also allowed inside the structure
definitions, so the structures may have some other structures as a
fields:
\begin{verbatim}
  struct LINE
    start POINT
    end   POINT
  ends
\end{verbatim}
When no default values for substructure fields are specified, as
in this example, the defaults from the definition of the type of
substructure apply.

Since value for each field is a single parameter in the
declaration of the structure, to initialize the substructures with
custom values the parameters for each substructure must be grouped
into a single parameter for the structure:
\begin{verbatim}
  line1 LINE <0,0>,<100,100>
\end{verbatim}
This declaration initializes each of the \verb"line1.start.x" and
\verb"line1.start.y" fields with 0, and each of the
\verb"line1.end.x" and \verb"line1.end.y" with 100.

When the size of data defined by some value passed to the
declaration structure is smaller than the size of corresponding
field, it is padded to that size with undefined bytes (and when it
is larger, the error happens). For example:
\begin{verbatim}
  struct FOO
    data db 256 dup (?)
  ends

  some FOO <"ABC",0>
\end{verbatim}
fills the first four bytes of \verb"some.data" with defined values
and reserves the rest.

Inside the structures also unions and unnamed substructures can be
defined. The definition of union should start with \verb"union"
and end with \verb"ends", like in this example:
\begin{verbatim}
  struct BAR
    field_1 dd ?
    union
      field_2  dd ?
      field_2b db ?
    ends
  ends
\end{verbatim}
Each of the fields defined inside union has the same offset and
they share the same memory. Only the first field of union is
initialized with given value, the values for the rest of fields
are ignored (however if one of the other fields requires more
memory than the first one, the union is padded to the required
size with undefined bytes). The whole union is initialized by the
single parameter given in structure declaration, and this
parameter gives value to the first field of union.

The unnamed substructure is defined in a similar way to the union,
only starts with the \verb"struct" line instead of \verb"union",
like:
\begin{verbatim}
  struct WBB
    word dw ?
    struct
      byte1 db ?
      byte2 db ?
    ends
  ends
\end{verbatim}
Such substructure only takes one parameter in the declaration of
whole structure to define its values, and this parameter can
itself be the group of parameters defining each field of the
substructure. So the above type of structure may get declared
like:
\begin{verbatim}
  my WBB 1,<2,3>
\end{verbatim}
The fields inside unions and unnamed substructures are accessed
just as if the were directly the fields of the parent structure.
For example with above declaration \verb"my.byte1" and
\verb"my.byte2" are correct labels for the substructure fields.

The substructures and unions can be nested with no limits for the
nesting depth:
\begin{verbatim}
  struct LINE
    union
      start POINT
      struct
        x1  dd ?
        y1  dd ?
      ends
    ends
    union
      end   POINT
      struct
        x2  dd ?
        y2  dd ?
      ends
    ends
  ends
\end{verbatim}

The definition of structure may also be based on some of the
already defined structure types and it inherits all the fields
from that structure, for example:
\begin{verbatim}
  struct CPOINT POINT
    color dd ?
  ends
\end{verbatim}
defines the same structure as:
\begin{verbatim}
  struct CPOINT
    x     dd ?
    y     dd ?
    color dd ?
  ends
\end{verbatim}

All headers define the \verb"CHAR" data type, which can be used to
define character strings in the data structures.

\subsection{Imports}
The import macroinstructions help to build the import data for PE
file (usually put in the separate section). There are two
macroinstructions for this purpose. The first one is called
\verb"library", must be placed directly in the beginning of the
import data and it defines from what libraries  the functions will
be imported. It should be followed by any amount of the pairs of
parameters, each pair being the label for the table of imports
from the given library, and the quoted string defining the name of
the library. For example:
\begin{verbatim}
  library kernel32,'KERNEL32.DLL',\
          user32,'USER32.DLL'
\end{verbatim}
declares to import from the two libraries. For each of libraries,
the table of imports must be then declared somewhere inside the
import data. This is done with \verb"import" macroinstruction,
which needs first parameter to define the label for the table (the
same as declared earlier to the \verb"library" macro), and then
the pairs of parameters each containing the label for imported
pointer and the quoted string defining the name of function
exactly as exported by library. For example the above
\verb"library" declaration may be completed with following
\verb"import" declarations:
\begin{verbatim}
  import kernel32,\
         ExitProcess,'ExitProcess'

  import user32,\
         MessageBeep,'MessageBeep',\
         MessageBox,'MessageBoxA'
\end{verbatim}
The labels defined by first parameters in each pair passed to the
\verb"import" macro address the double word pointers, which after
loading the PE are filled with the addresses to exported
procedures.

Instead of quoted string for the name of procedure to import, the
number may be given to define import by ordinal, like:
\begin{verbatim}
  import custom,\
         ByName,'FunctionName',\
         ByOrdinal,17
\end{verbatim}

The import macros optimize the import data, so only imports for
functions that are used somewhere in program are placed in the
import tables, and if some import table would be empty this way,
the whole library is not referenced at all. For this reason it's
handy to have the complete import table for each library -- the
package contains such tables for some of the standard libraries,
they are stored in the \verb"APIA" and \verb"APIW" subdirectories
and import the ASCII and WideChar variants of the API functions.
Each file contains one import table, with lowercase label the same
as the name of the file. So the complete tables for importing from
the \verb"KERNEL32.DLL" and \verb"USER32.DLL" libraries can be
defined this way (assuming your \verb"INCLUDE" environment
variable points to the directory containing the includes package):
\begin{verbatim}
  library kernel32,'KERNEL32.DLL',\
          user32,'USER32.DLL'

  include 'apia\kernel32.inc'
  include 'apiw\user32.inc'
\end{verbatim}

\subsection{Procedures (32--bit)}
Headers for 32--bit Windows provide four macroinstructions for calling procedures with
parameters passed on stack. The \verb"stdcall" calls directly the
procedure specified by the first argument using the STDCALL
calling convention. The rest of arguments passed to macro define
the parameters to procedure and are stored on the stack in reverse
order. The \verb"invoke" macro does the same, however it calls the
procedure indirectly, through the pointer labelled by the first
argument. Thus \verb"invoke" can be used to call the procedures
through pointers defined in the import tables. This line:
\begin{verbatim}
  invoke MessageBox,0,szText,szCaption,MB_OK
\end{verbatim}
is equivalent to:
\begin{verbatim}
  stdcall [MessageBox],0,szText,szCaption,MB_OK
\end{verbatim}
and they both generate this code:
\begin{verbatim}
  push MB_OK
  push szCaption
  push szText
  push 0
  call [MessageBox]
\end{verbatim}

The \verb"ccall" and \verb"cinvoke" are analogous to the
\verb"stdcall" and \verb"invoke", but they should be used to call
the procedures that use the C calling convention, where the stack
frame has to be restored by the caller.

To define the procedure that uses the stack for parameters and
local variables, you should use the \verb"proc" macroinstruction.
In its simplest form it has to be followed by the name for the
procedure and then names for the all the parameters it takes,
like:
\begin{verbatim}
  proc WindowProc,hwnd,wmsg,wparam,lparam
\end{verbatim}
The comma between the name of procedure and the first parameter is
optional. The procedure instructions should follow in the next
lines, ended with the \verb"endp" macroinstruction. The stack
frame is set up automatically on the entry to procedure, the EBP
register is used as a base to access the parameters, so you should
avoid using this register for other purposes. The names specified
for the parameters are used to define EBP-based labels, which you
can use to access the parameters as regular variables. For example
the \verb"mov eax,[hwnd]" instruction inside the procedure defined
as in above sample, is equivalent to \verb"mov eax,[ebp+8]". The
scope of those labels is limited to the procedure, so you may use
the same names for other purposes outside the given procedure.

Since any parameters are pushed on the stack as double words when
calling such procedures, the labels for parameters are defined to
mark the double word data by default, however you can you specify
the sizes for the parameters if you want, by following the name of
parameter with colon and the size operator. The previous sample
can be rewritten this way, which is again equivalent:
\begin{verbatim}
  proc WindowProc,hwnd:DWORD,wmsg:DWORD,wparam:DWORD,lparam:DWORD
\end{verbatim}
If you specify a size smaller than double word, the given label
applies to the smaller portion of the whole double word stored on
stack. If you you specify a larger size, like far pointer of quad
word, the two double word parameters are defined to hold this
value, but are labelled as one variable.

The name of procedure can be also followed by either the
\verb"stdcall" or \verb"c" keyword to define the calling
convention it uses. When no such type is specified, the default is
used, which is equivalent to STDCALL. Then also the \verb"uses"
keyword may follow, and after it the list of registers (separated
only with spaces) that will be automatically stored on entry to
procedure and restored on exit. In this case the comma after the
list of registers and before the first parameter is required. So
the fully featured procedure statement might look like this:
\begin{verbatim}
  proc WindowProc stdcall uses ebx esi edi,\
       hwnd:DWORD,wmsg:DWORD,wparam:DWORD,lparam:DWORD
\end{verbatim}

To declare the local variable you can use the \verb"local"
macroinstruction, followed by one or more declarations separated
with commas, each one consisting of the name for variable followed
by colon and the type of variable -- either one of the standard
types (must be upper case) or the name of data structure. For
example:
\begin{verbatim}
  local hDC:DWORD,rc:RECT
\end{verbatim}
To declare a local array, you can follow the name of variable by
the size of array enclosed in square brackets, like:
\begin{verbatim}
  local str[256]:BYTE
\end{verbatim}
The other way to define the local variables is to declare them
inside the block started with "locals" macroinstruction and ended
with "endl", in this case they can be defined just like regular
data. This declaration is the equivalent of the earlier sample:
\begin{verbatim}
  locals
    hDC dd ?
    rc RECT
  endl
\end{verbatim}
The local variables can be declared anywhere inside the procedure,
with the only limitation that they have to be declared before they
are used. The scope of labels for the variables defined as local
is limited to inside the procedure, you can use the same names for
other purposes outside the procedure. If you give some initialized
values to the variables declared as local, the macroinstruction
generates the instructions that will initialize these variables
with the given values and puts these instruction at the same
position in procedure, where the declaration is placed.

The \verb"ret" placed anywhere inside the procedure, generates the
complete code needed to correctly exit the procedure, restoring
the stack frame and the registers used by procedure. If you need
to generate the raw return instruction, use the \verb"retn"
mnemonic, or follow the \verb"ret" with the number parameter, what
also causes it to be interpreted as single instruction.

To recapitulate, the complete definition of procedure may look
like this:
\begin{verbatim}
  proc WindowProc uses ebx esi edi,hwnd,wmsg,wparam,lparam
    local hDC:DWORD,rc:RECT
    ; the instructions
    ret
  endp
\end{verbatim}

\subsection{Procedures (64--bit)}

In 64--bit Windows there is only one calling convention, and thus only two macroinstructions for calling procedures are provided.
The \verb"fastcall" calls directly the procedure specified by the first argument using the standard convention of 64--bit Windows system.
The \verb"invoke" macro does the same, but indirectly, through the pointer labelled by the first argument.
Parameters are provided by the arguments that follow, and they can be of any size up to 64 bits.
The macroinstructions use RAX register as a temporary storage when some parameter value cannot be copied directly into the stack using the
\verb"mov" instruction. If the parameter is preceded with \verb"addr" word, it is treated as an address and is
calculated with the \verb"lea" instruction -- so if the address is absolute, it will get calculated as RIP-relative,
thus preventing generating a relocation in case of file with fixups.

Because in 64--bit Windows the floating--point parameters are passed in a different way, they have to be marked by preceding each one of them
with \verb"float" word. They can be either double word or quad word in size.
Here is an example of calling some OpenGL procedures with either double--precision or single--precision parameters:
\begin{verbatim}
  invoke glVertex3d,float 0.6,float -0.6,float 0.0
  invoke glVertex2f,float dword 0.1,float dword 0.2
\end{verbatim}

The stack space for parameters are allocated before each call and freed immediately after it.
However it is possible to allocate this space just once for all the calls inside some given block of code,
for this purpose there are \verb"frame" and \verb"endf" macros provided. They should be used to enclose a block,
inside which the RSP register is not altered between the procedure calls and they prevent each call from allocating
stack space for parameters, as it is reserved just once by the \verb"frame" macro and then freed at the end by the \verb"endf" macro.
\begin{verbatim}
  frame ; allocate stack space just once
    invoke TranslateMessage,msg
    invoke DispatchMessage,msg
  endf
\end{verbatim}
The \verb"proc" macro for 64--bit Windows has the same syntax and features as 32--bit one (though \verb"stdcall" and \verb"c" options are of no use in its case).
It should be noted however that in the calling convention used in 64--bit Windows first four parameters are passed in registers (RCX, RDX, R8 and R9),
and therefore, even though there is a space reserved for them at the stack and it is labelled with name provided in the procedure definition,
those four parameters will not initially reside there. They should be accessed by directly reading the registers. But if those registers are
needed to be used for some other purpose, it is recommended to store the value of such parameter into the memory cell reserved for it.
The beginning of such procedure may look like:
\begin{verbatim}
  proc WindowProc hwnd,wmsg,wparam,lparam
    mov [hwnd],rcx
    mov [wmsg],edx
    mov [wparam],r8
    mov [lparam],r9
    ; now registers can be used for other purpose
    ; and parameters can still be accessed later
\end{verbatim}

\subsection{Customizing procedures}
It is possible to create a custom code for procedure framework when using \verb"proc" macroinstruction.
There are three symbolic variables, \verb"prologue@proc", \verb"epilogue@proc" and \verb"close@proc",
which define the names of macroinstructions that \verb"proc" calls upon entry to the procedure,
return from procedure (created with \verb"ret" macro) and at the end of procedure (made with \verb"endp" macro).
Those variables can be re--defined to point to some other macroinstructions, so that all the code
generated with \verb"proc" macro can be customized.

Each of those three macroinstructions takes five parameters.
The first one provides a label of procedure entry point, which is the name of procedure aswell.
The second one is a bitfield containing some flags, notably the bit 4 is set when the caller is supposed to restore the stack, and cleared otherwise.
The third one is a value that specifies the number of bytes that parameters to the procedure take on the stack.
The fourth one is a value that specified the number of bytes that should be reserved for the local variables.
Finally, the fifth an last parameter is the list of comma--separated registers, which procedure declared to be used
and which should therefore be saved by prologue and restored by epilogue.

The prologue macro apart from generating code that would set up the stack frame and the pointer to local variables
has to define two symbolic variables, \verb"parmbase@proc" and \verb"localbase@proc".
The first one should provide the base address for where the parameters reside, and the second
one should provide the address for where the local variables reside -- usually relative to
EBP/RBP register, but it is possible to use other bases if it can be ensured that those pointers
will be valid at any point inside the procedure where parameters or local variables are accessed.
It is also up to the prologue macro to make any alignments necessary for valid procedure implementation;
the size of local variables provided as fourth parameter may itself be not aligned at all.

The default behavior of \verb"proc" is defined by \verb"prologuedef" and \verb"epiloguedef" macros
(in default case there is no need for closing macro, so the \verb"close@proc" has an empty value).
If it is needed to return to the defaults after some customizations were used, it should be done
with the following three lines:
\begin{verbatim}
  prologue@proc equ prologuedef
  epilogue@proc equ epiloguedef
  close@proc equ
\end{verbatim}

As an example of modified prologue, below is the macroinstruction that implements stack-probing prologue for
32--bit Windows. Such method of allocation should be used every time the area of local variables may
get larger than 4096 bytes.
\begin{verbatim}
  macro sp_prologue procname,flag,parmbytes,localbytes,reglist
  { local loc
    loc = (localbytes+3) and (not 3)
    parmbase@proc equ ebp+8
    localbase@proc equ ebp-loc
    if parmbytes | localbytes
     push ebp
     mov ebp,esp
     if localbytes
      repeat localbytes shr 12
       mov byte [esp-%*4096],0
      end repeat
      sub esp,loc
     end if
    end if
    irps reg, reglist \{ push reg \} }

  prologue@proc equ sp_prologue
\end{verbatim}
It can be easily modified to use any other stack probing method of the programmer's preference.

The 64--bit headers provide an additional set of prologue/epilogue macros, which allow to define
procedure that uses RSP to access parameters and local variables (so RBP register is free to use for any other by procedure)
and also allocates the common space for all the procedure calls made inside, so that \verb"fastcall"
or \verb"invoke" macros called do not need to allocate any stack space themselves. It is an effect
similar to the one obtained by putting the code inside the procedure into \verb"frame" block, but in
this case the allocation of stack space for procedure calls is merged with the allocation of space
for local variables. The code inside such procedure must not alter RSP register in any way.
To switch to this behavior of 64--bit \verb"proc", use the following instructions:
\begin{verbatim}
  prologue@proc equ static_rsp_prologue
  epilogue@proc equ static_rsp_epilogue
  close@proc equ static_rsp_close
\end{verbatim}


\subsection{Exports}
The \verb"export" macroinstruction constructs the export data for
the PE file (it should be either placed in the section marked as
export, or within the \verb"data export" block. The first argument
should be quoted string defining the name of library file, and the
rest should be any number of pairs of arguments, first in each
pair being the name of procedure defined somewhere inside the
source, and the second being the quoted string containing the name
under which this procedure should be exported by the library. This
sample:
\begin{verbatim}
  export 'MYLIB.DLL',\
         MyStart,'Start',\
         MyStop,'Stop'
\end{verbatim}
defines the table exporting two functions, which are defined under
the names \verb"MyStart" and \verb"MyStop" in the sources, but
will be exported by library under the shorter names. The
macroinstruction take care of the alphabetical sorting of the
table, which is required by PE format.

\subsection{Component Object Model}
The \verb"interface" macro allows to declare the interface of the
COM object type, the first parameter is the name of interface, and
then the consecutive names of the methods should follow, like in
this example:
\begin{verbatim}
  interface ITaskBarList,\
             QueryInterface,\
             AddRef,\
             Release,\
             HrInit,\
             AddTab,\
             DeleteTab,\
             ActivateTab,\
             SetActiveAlt
\end{verbatim}

The \verb"comcall" macro may be then used to call the method of
the given object. The first parameter to this macro should be the
handle to object, the second one should be name of COM interface
implemented by this object, and then the name of method and
parameters to this method. For example:
\begin{verbatim}
  comcall ebx,ITaskBarList,ActivateTab,[hwnd]
\end{verbatim}
uses the contents of EBX register as a handle to COM object with
the \verb"ITaskBarList" interface, and calls the
\verb"ActivateTab" method of this object with the \verb"[hwnd]"
parameter.

You can also use the name of COM interface in the same way as the
name of data structure, to define the variable that will hold the
handle to object of given type:
\begin{verbatim}
  ShellTaskBar ITaskBarList
\end{verbatim}
The above line defines the variable, in which the
handle to COM object can be stored. After storing there the handle
to an object, its methods can be called with the \verb"cominvk".
This macro needs only the name of the variable with assigned
interface and the name of method as first two parameters, and then
parameters for the method. So the \verb"ActivateTab" method of
object whose handle is stored in the \verb"ShellTaskBar" variable
as defined above can be called this way:
\begin{verbatim}
  cominvk ShellTaskBar,ActivateTab,[hwnd]
\end{verbatim}
which does the same as:
\begin{verbatim}
  comcall [ShellTaskBar],ITaskBarList,ActivateTab,[hwnd]
\end{verbatim}

\subsection{Resources}
There are two ways to create resources, one is to include the
external resource file created with some other program, and the
other one is to create resource section manually. The latter
method, though doesn't need any additional program to be involved,
is more laborious, but the standard headers provide the assistance
-- the set of elementary macroinstructions that serve as bricks to
compose the resource section.

The \verb"directory" macroinstruction must be placed directly in
the beginning of manually built resource data and it defines what
types of resources it contains. It should be followed by the pairs
of values, the first one in each pair being the identifier of the
type of resource, and the second one the label of subdirectory of
the resources of given type. It may look like this:
\begin{verbatim}
  directory RT_MENU,menus,\
            RT_ICON,icons,\
            RT_GROUP_ICON,group_icons
\end{verbatim}

The subdirectories can be placed anywhere in the resource area
after the main directory, and they have to be defined with the
\verb"resource" macroinstruction, which requires first parameter
to be the label of the subdirectory (corresponding to the entry in
main directory) followed by the trios of parameters -- in each
such entry the first parameter defines the identifier of resource
(this value is freely chosen by the programmer and is then used to
access the given resource from the program), the second specifies
the language and the third one is the label of resource. Standard
equates should be used to create language identifiers. For example
the subdirectory of menus may be defined this way:
\begin{verbatim}
  resource menus,\
           1,LANG_ENGLISH+SUBLANG_DEFAULT,main_menu,\
           2,LANG_ENGLISH+SUBLANG_DEFAULT,other_menu
\end{verbatim}
If the resource is of kind for which the language doesn't matter,
the language identifier \verb"LANG_NEUTRAL" should be used. To define the
resources of various types there are specialized
macroinstructions, which should be placed inside the resource
area.

The bitmaps are the resources with \verb"RT_BITMAP" type
identifier. To define the bitmap resource use the \verb"bitmap"
macroinstruction with the first parameter being the label of
resource (corresponding to the entry in the subdirectory of
bitmaps) and the second being the quoted string containing the
path to the bitmap file, like:
\begin{verbatim}
  bitmap program_logo,'logo.bmp'
\end{verbatim}

The are two resource types related to icons, the
\verb"RT_GROUP_ICON" is the type for the resource, which has to be
linked to one or more resources of \verb"RT_ICON" type, each one
containing single image. This allows to declare images of
different sizes and color depths under the common resource
identifier. This identifier, given to the resource of
\verb"RT_GROUP_ICON" type may be then passed to the
\verb"LoadIcon" function, and it will choose the image of suitable
dimensions from the group. To define the icon, use the \verb"icon"
macroinstruction, with first parameter being the label of
\verb"RT_GROUP_ICON" resource, followed by the pairs of parameters
declaring the images. First parameter in each pair should be the
label of \verb"RT_ICON" resource, and the second one the quoted
string containing the path to the icon file. In the simplest
variant, when group of icon contains just one image, it will look
like:
\begin{verbatim}
  icon main_icon,icon_data,'main.ico'
\end{verbatim}
where the \verb"main_icon" is the label for entry in resource
subdirectory for \verb"RT_GROUP_ICON" type, and the
\verb"icon_data" is the label for entry of \verb"RT_ICON" type.

The cursors are defined in a way similar to icons,
with the \verb"RT_GROUP_CURSOR" and \verb"RT_CURSOR" types and the
\verb"cursor" macro, which takes parameters analogous to those
taken by \verb"icon" macro. So the definition of cursor may look
like this:
\begin{verbatim}
  cursor my_cursor,cursor_data,'my.cur'
\end{verbatim}

The menus have the \verb"RT_MENU" type of resource and are defined
with the \verb"menu" macroinstruction followed by few others
defining the items inside the menu. The \verb"menu" itself takes
only one parameter -- the label of resource. The \verb"menuitem"
defines the item in the menu, it takes up to five parameters, but
only two are required -- the first one is the quoted string
containing the text for the item, and the second one is the
identifier value (which is the value that will be returned when
user selects the given item from the menu). The
\verb"menuseparator" defines a separator in the menu and doesn't
require any parameters.

The optional third parameter of \verb"menuitem" specifies the menu
resource flags. There are two such flags available --
\verb"MFR_END" is the flag for the last item in the given menu,
and the \verb"MFR_POPUP" marks that the given item is the submenu,
and the following items will be items composing that submenu until
the item with \verb"MFR_END" flag is found. The \verb"MFR_END"
flag can be also given as the parameter to the
\verb"menuseparator" and is the only parameter this
macroinstruction can take. For the menu definition to be complete,
every submenu must be closed by the item with \verb"MFR_END" flag,
and the whole menu must also be closed this way. Here is an
example of complete definition of the menu:
\begin{verbatim}
  menu main_menu
       menuitem '&File',100,MFR_POPUP
                menuitem '&New',101
                menuseparator
                menuitem 'E&xit',109,MFR_END
       menuitem '&Help',900,MFR_POPUP + MFR_END
                menuitem '&About...',901,MFR_END
\end{verbatim}

The optional fourth parameter of \verb"menuitem" specifies the
state flags for the given item, these flags are the same as the
ones used by API functions, like \verb"MFS_CHECKED" or
\verb"MFS_DISABLED". Similarly, the fifth parameter can specify
the type flags. For example this will define item checked with a
radio--button mark:
\begin{verbatim}
  menuitem 'Selection',102, ,MFS_CHECKED,MFT_RADIOCHECK
\end{verbatim}

The dialog boxes have the \verb"RT_DIALOG" type of resource and
are defined with the \verb"dialog" macroinstruction followed by
any number of items defined with \verb"dialogitem" ended with the
\verb"enddialog".

The \verb"dialog" can take up to eleven parameters, first seven
being required. First parameter, as usual, specifies the label of
resource, second is the quoted string containing the title of the
dialog box, the next four parameters specify the horizontal and
vertical coordinates, the width and the height of the dialog box
window respectively. The seventh parameter specifies the style
flags for the dialog box window, the optional eighth one specifies
the extended style flags. The ninth parameter can specify the menu
for window -- it should be the identifier of menu resource, the
same as one specified in the subdirectory of resources with
\verb"RT_MENU" type. Finally the tenth and eleventh parameter can
be used to define the font for the dialog box -- first of them
should be the quoted string containing the name of font, and the
latter one the number defining the size of font. When these
optional parameters are not specified, the default MS Sans Serif
of size 8 is used.

This example shows the \verb"dialog" macroinstruction with all the
parameters except for the menu (which is left with blank value),
the optional ones are in the second line:
\begin{verbatim}
  dialog about,'About',50,50,200,100,WS_CAPTION+WS_SYSMENU,\
               WS_EX_TOPMOST, ,'Times New Roman',10
\end{verbatim}

The \verb"dialogitem" has eight required parameters and one
optional. First parameter should be the quoted string containing
the class name for the item. Second parameter can be either the
quoted string containing text for the item, or resource identifier
in case when the contents of item has to be defined by some
additional resource (like the item of \verb"STATIC" class with the
\verb"SS_BITMAP" style). The third parameter is the identifier for
the item, used to identify the item by the API functions. Next
four parameters specify the horizontal, vertical coordinates, the
width and height of the item respectively. The eighth parameter
specifies the style for the item, and the optional ninth specifies
the extended style flags. An example dialog item definition:
\begin{verbatim}
  dialogitem 'BUTTON','OK',IDOK,8,8,45,15,WS_VISIBLE+WS_TABSTOP
\end{verbatim}
And an example of static item containing bitmap, assuming that
there exists a bitmap resource of identifier 7:
\begin{verbatim}
  dialogitem 'STATIC',7,0,10,50,50,20,WS_VISIBLE+SS_BITMAP
\end{verbatim}

The definition of dialog resource can contain any amount of items
or none at all, and it should be always ended with
\verb"enddialog" macroinstruction.

The resources of type \verb"RT_ACCELERATOR" are created with
\verb"accelerator" macroinstruction. After first parameter
traditionally being the label of resource, there should follow the
trios of parameters -- the accelerator flags followed by the
virtual key code or ASCII character and the identifier value
(which is like the identifier of the menu item). A simple
accelerator definition may look like this:
\begin{verbatim}
  accelerator main_keys,\
              FVIRTKEY+FNOINVERT,VK_F1,901,\
              FVIRTKEY+FNOINVERT,VK_F10,109
\end{verbatim}

The version information is the resource of type \verb"RT_VERSION"
and is created with the \verb"versioninfo" macroinstruction. After the
label of the resource, the second parameter specifies the
operating system of PE file (usually it should be
\verb"VOS__WINDOWS32"), third parameter the type of file (the most
common are \verb"VFT_APP" for program and \verb"VFT_DLL" for
library), fourth the subtype (usually \verb"VFT2_UNKNOWN"), fifth
the language identifier, sixth the code page and then the quoted
string parameters, being the pairs of property name and
corresponding value. The simplest version information can be
defined like:
\begin{verbatim}
  versioninfo vinfo,VOS__WINDOWS32,VFT_APP,VFT2_UNKNOWN,\
                    LANG_ENGLISH+SUBLANG_DEFAULT,0,\
              'FileDescription','Description of program',\
              'LegalCopyright','Copyright et cetera',\
              'FileVersion','1.0',\
              'ProductVersion','1.0'
\end{verbatim}

Other kinds of resources may be defined with \verb"resdata"
macroinstruction, which takes only one parameter -- the label of
resource, and can be followed by any instructions defining the
data, ended with \verb"endres" macroinstruction, like:
\begin{verbatim}
  resdata manifest
    file 'manifest.xml'
  endres
\end{verbatim}

\subsection{Text encoding}
The resource macroinstructions use the \verb"du" directive to
define any Unicode strings inside resources -- since this
directive simply zero extends the characters to the 16--bit
values, for the strings containing some non--ASCII characters, the
\verb"du" may need to be redefined. For some of the encodings the
macroinstructions redefining the \verb"du" to generate the Unicode
texts properly are provided in the \verb"ENCODING" subdirectory.
For example if the source text is encoded with Windows 1250 code
page, such line should be put somewhere in the beginning of the
source:
\begin{verbatim}
  include 'encoding\win1250.inc'
\end{verbatim}

\section{Extended headers}
The files \verb"win32ax.inc", \verb"win32wx.inc", \verb"win64ax.inc" and \verb"win64wx.inc"
provide all the functionality of base headers and include a few
more features involving more complex macroinstructions. Also if no
PE format is declared before including the extended headers, the
headers declare it automatically. The files \verb"win32axp.inc",
\verb"win32wxp.inc", \verb"win64axp.inc" and \verb"win64wxp.inc"
are the variants of extended headers which
additionally perform checking the count of parameters to procedure
calls.

\subsection{Procedure parameters}
With the extended headers the macroinstructions for calling
procedures allow more types of parameters than just the double
word values as with basic headers. First of all, when the quoted
string is passes as a parameter to procedure, it is used to define
string data placed among the code, and passes to procedure the
double word pointer to this string. This allows to easily define
the strings that don't have to be re-used, just in the line
calling the procedure that requires pointers to those strings,
like:
\begin{verbatim}
  invoke MessageBox,HWND_DESKTOP,"Message","Caption",MB_OK
\end{verbatim}
If the parameter is the group containing some values separated
with commas, it is treated in the same way as simple quoted string
parameter.

If the parameter is preceded by the \verb"addr" word, it means
that this value is an address and this address should
be passed to procedure, even if it cannot be done directly -- like
in the case of local variables, which have addresses relative to
EBP/RBP register. In 32--bit case the EDX register is used temporarily to
calculate the value of address and pass it to the procedure. For
example:
\begin{verbatim}
  invoke RegisterClass,addr wc
\end{verbatim}
in case when the \verb"wc" is the local variable with address
\verb"ebp-100h", will generate this sequence of instructions:
\begin{verbatim}
  lea edx,[ebp-100h]
  push edx
  call [RegisterClass]
\end{verbatim}
However when the given address is not relative to any register, it
is stored directly.

In 64--bit case the \verb"addr" prefix is allowed even when only standard
headers are used, as it can be useful even in case of the regular addresses,
because it enforces RIP-relative address calculation.

With 32--bit headers, if the parameter is preceded by the word \verb"double", it is
treated as 64--bit value and passed to the procedure as two
32--bit parameters. For example:
\begin{verbatim}
  invoke glColor3d,double 1.0,double 0.1,double 0.1
\end{verbatim}
will pass the three 64--bit parameters as six double words to
procedure. If the parameter following \verb"double" is the memory
operand, it should not have size operator, the \verb"double"
already works as the size override.

Finally, the calls to procedures can be nested, that is call to
one procedure may be used as the parameter to another. In such
case the value returned in EAX/RAX by the nested procedure is passed
as the parameter to the procedure which it is nested in. A sample
of such nesting:
\begin{verbatim}
  invoke MessageBox,<invoke GetTopWindow,[hwnd]>,\
                    "Message","Caption",MB_OK
\end{verbatim}
There are no limits for the depth of nesting the procedure calls.

\subsection{Structuring the source}
The extended headers enable some macroinstructions that help with
easy structuring the program. The \verb".data" and \verb".code"
are just the shortcuts to the declarations of sections for data
and for the code. The \verb".end" macroinstruction should be put
at the end of program, with one parameter specifying the entry
point of program, and it also automatically generates the import
section using all the standard import tables. In 64--bit Windows
the \verb".end" automatically aligns the stack on 16 bytes
boundary.

The \verb".if" macroinstruction generates a piece of code that
checks for some simple condition at the execution time, and
depending on the result continues execution of following block or
skips it. The block should be ended with \verb".endif", but
earlier also \verb".elseif" macroinstruction might be used to
begin the code that will be executed under some additional
condition, when the previous were not met, and the \verb".else" as
the last before \verb".endif" to begin the block that will be
executed when all the conditions were false.

The condition can be specified by using comparison operator -- one of the \verb"=",
\verb"<", \verb">", \verb"<=", \verb">=", and \verb"<>" -- between the two
values, first of which must be either register or memory operand.
The values are compared as unsigned ones, unless the comparison expression is preceded by the word \verb"signed".
If you provide only single value as a condition, it will be tested to be zero,
and the condition will be true only if it's not. For example:
\begin{verbatim}
  .if eax
    ret
  .endif
\end{verbatim}
generates the instructions, which skip over the \verb"ret" when the EAX is zero.

There are also some special symbols recognized as conditions: the \verb"ZERO?" is true when the ZF flag is set,
in the same way the \verb"CARRY?", \verb"SIGN?", \verb"OVERFLOW?" and \verb"PARITY?" correspond to the state of CF, SF, OF and PF flags.

The simple conditions like above can be composed into complex conditional expressions
using the \verb"&", \verb"|" operators for conjunction and alternative, the \verb"~" operator for negation, and parenthesis. For example:
\begin{verbatim}
  .if eax<=100 & ( ecx | edx )
    inc ebx
  .endif
\end{verbatim}
will generate the compare and jump instructions that will cause the given block to get executed only when EAX is below or
equal 100 and at the same time at least one of the ECX and EDX is not zero.

The \verb".while" macroinstruction generates the instructions that
will repeat executing the given block (ended with \verb".endw"
macroinstruction) as long as the condition is true. The condition
should follow the \verb".while" and can be specified in the same
way as for the \verb".if". The pair of \verb".repeat" and
\verb".until" macroinstructions define the block that will be
repeatedly executed until the given condition will be met -- this
time the condition should follow the \verb".until"
macroinstruction, placed at the end of block, like:
\begin{verbatim}
  .repeat
    add ecx,2
  .until ecx>100
\end{verbatim}

\end{document}