Differences

This shows you the differences between two versions of the page.

--- en:edu:zmitac:s1:apl:lab:lab1 [2024/11/18 21:46] – [Practice: Task to be performed] ktokarz
+++ en:edu:zmitac:s1:apl:lab:lab1 [2026/09/16 11:58] (current) – Accessibility: add WCAG-compliant alt texts to all nine figures mcp_agent
@@ Line 2: / Line 2: @@
 ===== Laboratory 1 =====
-Programming in Assembler Laboratory, exercise 1
+Configuration of the Visual Studio for simple assembler application written in MASM.
-==== Instroduction ====
+===== Introduction =====
 In this exercise, you will create a console application in pure assembler for x64 (Intel/AMD processors, 64 bits) that will interact with the Windows operating system (Windows 7, 8, 8.1, 10, 11) by calling its functions via the Windows API.
@@ Line 84: / Line 84: @@
 Create a new project: a command-line (console) application for C++, native (__not C++ .NET__) figure {{ref>jalabstep1}}
 <figure jalabstep1>
-{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_01_48.png?1000|}}
+{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_01_48.png?1000|Visual Studio "Create a new project" dialogue with the C++ language filter applied and the "Console App" template highlighted in the template list; the Next button is located in the bottom right corner.}}
 <caption>Creating a C++ project, native code</caption>
 </figure>
@@ Line 91: / Line 91: @@
 Delete the generated .cpp file (from VS) and then add a new .asm file (this can be done by clicking on the project (not the solution!) and selecting to add a new element figure {{ref>jalabstep21}}, then select the text file and change its name and extension figure {{ref>jalabstep22}}:
 <figure jalabstep21>
-{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_07_27.png?1000|}}
+{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_07_27.png?1000|Visual Studio project context menu opened from the Solution Explorer, with the "Add" submenu expanded and the "New Item..." entry (shortcut Ctrl+Shift+A) highlighted.}}
 <caption>Adding a new element</caption>
 </figure>
 <figure jalabstep22>
-{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_08_50.png?1000|}}
+{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_08_50.png?1000|Visual Studio "Add New Item" dialogue with the Visual C++ Utility category selected, the "Text File (.txt)" template chosen and the Name field set to source.asm; the Add button is located in the bottom right corner.}}
 <caption>Adding a new element - asm file</caption>
 </figure>
@@ Line 103: / Line 103: @@
 <figure jalabstep31>
-{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_17_17.png?1000|}}
+{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_17_17.png?1000|Visual Studio project context menu with the "Build Dependencies" entry highlighted and its submenu expanded, showing the single option "Build Customizations...".}}
 <caption>Choosing the project build customization menu</caption>
@@ Line 109: / Line 109: @@
 <figure jalabstep32>
-{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_17_40.png?1000|}}
+{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_17_40.png?1000|Visual Studio "Visual C++ Build Customization Files" dialogue listing the available customisation files with their paths; only the "masm(.targets, .props)" check box is ticked, and the OK button is located at the bottom.}}
 <caption>Choosing the MASM compiler</caption>
@@ Line 116: / Line 116: @@
 Next, change the type of application being built from ''x86'' (32-bit application) to ''x64'' (64-bit application): Build->Configuration Manager menu figure {{ref>jalabstep4}}.
 <figure jalabstep4>
-{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_21_07.png?1000|}}
+{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_21_07.png?1000|Visual Studio "Configuration Manager" dialogue with the active solution configuration set to Debug and the active solution platform set to x64; the project row shows the AssemblerLab1 project with configuration Debug, platform x64 and the Build check box ticked.}}
 <caption>Environment configuration - building the 64-bit version</caption>
 </figure>
@@ Line 129: / Line 129: @@
 <figure jalabstep51>
-{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_09_06_12.png?1000|}}
+{{:en:edu:zmitac:s1:apl:lab:virtualbox_msedge_-_win10_18_11_2024_09_06_12.png?1000|Visual Studio project Property Pages dialogue for the Active(Debug) configuration and Active(x64) platform, with the Configuration Properties, Linker, Advanced section selected; the "Entry Point" property in the first row is highlighted and contains the value hello_world_asm.}}
 <caption>Configuration of the program entry point</caption>
 </figure>
@@ Line 140: / Line 140: @@
 Details in figure {{ref>jalabstep52}}.
 <figure jalabstep52>
-{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_50_25.png?1000|}}
+{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_12_03_2021_08_50_25.png?1000|Visual Studio project Property Pages dialogue with the Configuration Properties, Linker, Input section selected and the "Additional Dependencies" editor window open; the upper text field contains legacy_stdio_definitions.lib and legacy_stdio_wide_specifiers.lib, one per line, and the "Inherited values" list below starts with kernel32.lib and user32.lib.}}
 <caption>Configuring additional libraries</caption>
 </figure>
@@ Line 147: / Line 147: @@
 In some cases, the ''.asm'' file is not automatically recognized as a source file with assembler code. Therefore, you must explicitly inform the environment about this. To do this, right-click the file name in the project tree and select ''Properites'', then in the ''General'' section, select ''Item Type'' and set its value to ''Microsoft Macro Assembler''. Details in figure {{ref>jalabstep6}}.
 <figure jalabstep6>
-{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_27_03_2021_19_44_41.png?1000|}}
+{{:pl:edu:zmitac:n1z:ja:virtualbox_msedge_-_win10_27_03_2021_19_44_41.png?1000|Visual Studio Property Pages dialogue for the file source.asm with the Configuration Properties, General section selected; the "Item Type" drop-down list is expanded and the "Microsoft Macro Assembler" entry is selected.}}
 <caption>Marking an ASM file as a source file with assembler code</caption>
 </figure>
@@ Line 260: / Line 260: @@
 ...
 </code>
+In the above example, the value returned by the function (via the RAX register) is saved in the variable ''handler'', of the DQ type (64 bits, i.e. simply an address in memory).
+To read the handle to the inside of the terminal, you need to use another function:
+<code>
+...
+mov rcx, STD_OUTPUT_HANDLE
+call GetStdHandle
+mov stdHandle, rax
+...
+</code>
+However, this function requires one argument, which data stream we want. There are three possibilities:
+  * STD_INPUT_HANDLE = -10 - standard input - it can be used to read data from the console
+  * STD_OUTPUT_HANDLE = -11 - standard output - it is used to write something in the terminal; remember the ending ENTER, i.e. ''13,10''!;
+  * STD_ERROR_HANDLE = -12 - stream for errors;
+An example code that displays the text in the variable (at the address) ''text_msg'' on the console is below. The first parameter is the console handle read above. In the third parameter, you need to specify how many characters should be displayed. The fourth parameter is a pointer to where the function will return information about how many characters it actually displayed (it's not entirely clear what this is for).
+<code>
+...
+; WINAPI WriteConsoleA(
+; RCX => _In_ HANDLE hConsoleOutput,
+; RDX => _In_ const VOID *lpBuffer,
+; R8 => _In_ DWORD nNumberOfCharsToWrite,
+; R9 => _Out_opt_ LPDWORD lpNumberOfCharsWritten,
+mov rcx, stdHandle
+lea rdx, text_msg
+mov r8, sizeof text_msg
+mov r9, dummy
+call WriteConsoleA
+...
+</code>
+To display a dialogue box, use a pointer to the main application window. The parameters passed in this order are a handle, two pointers, to texts (they must end with a zero, RDX is a pointer to the content that the dialogue box will display, and R8 is a pointer to the window header that will be given to the window) that are to appear in header and dialogue body and finally, a binary mask specifying which buttons and icons to use in the dialogue box ((https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-messageboxa)).
+<code>
+...
+; WINUSERAPI int WINAPI MessageBoxA(
+; RCX => _In_opt_ HWND hWnd,
+; RDX => _In_opt_ LPCSTR lpText,
+; R8 => _In_opt_ LPCSTR lpCaption,
+; R9 => _In_ UINT uType);
+mov rcx, handler
+mov rdx, offset hello_msg
+mov r8, offset info_msg
+mov r9, 0 ; MB_OK
+and rsp, not 8
+call MessageBoxA
+...
+</code>
+<note important>Note - in the above case, the stack was explicitly aligned to a value divisible by 16 with the instruction (''and rsp, not 8''). It is a requirement of the x64 Windows calling convention. If you call the system function you should take care to align the stack pointer so that it is divisible by 16.</note>
+==== Tasks to be done for the report ====
+Let's start wth debugging. If the program runs correctly please set the breakpoint at the beginning of assembly code. Open register window and observe the content of registers after instruction execution. Please do not step into Windows functions including WriteConsoleA() and MessageBoxA(), use step over instead. In the report answer the following questions.
+  * RIP - note how its content differs with every instruction in the series. Do changes depend on the type of instruction executed? Compare changes with the disassembly window and the number of bytes instructions occupy.
+  * While calling WriteConsoleA look at the memory dump window at the address stored in RDX. What is there in the memory? You can try different view modes.
+  * While calling MessageBoxA function look at the memory dump window at the address stored in RDX and in R8. What is there in the memory? You can try different view modes.
+  * Include in the program the instruction which sets the RAX to some chosen value e.g. 00FFh before calling previously mentioned functions. Does the RAX register content change after returning from these functions?
+  * Try to replace the instruction "mov rdx, offset hello_msg" with "lea" instruction (of course with proper argument). Explain if they are identical or not.
+==== Method of results verification ====
+The texts and windows that appear on the screen should correspond to the algorithm. Pay special attention to whether random strings of characters are generated, which may suggest that you forgot about the ending 0.