RAU6 Dokuwiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Programming in Assembler Laboratory ======
===== Laboratory 2 =====
Configuration of the Visual Studio Community 2019 for dll libraries written in MASM.

===== Creating the project with dll library written in assembler =====

In the beginning, we can create a project in which the main program will be written in HLL (High-Level Language) like C++, and the library written in assembler will be linked dynamically (dll). 
<note tip>Creation of libraries written in assembly language, with functions called from the application written in a chosen high-level language is currently the most common assembler use.</note>
<note>The configuration process presented in the following slides can slightly differ in other versions of Visual Studio and is identical to the main program written in C++ and C#. The screenshots used are from the DLL configuration for both programming languages, but the differences are usually secondary and do not affect the environment configuration process.</note>
==== Creating of the new project ====
During this laboratory, we'll show how to create and use dll (dynamically linked library) written in assembler in that application written in C++
We start by creating a new C++ project. 

{{ :pl:edu:zmitac:n1z:ja:create_step1.jpg?800 |}}

We'll create the console application, written in C++, for execution in the Windows operating system.

{{ :pl:edu:zmitac:n1z:ja:create_1.jpg?800 |}}

We need to define that name for the project. We suggest the name "Lab2_dll_cpp". All paths can be left with default values.

{{ :pl:edu:zmitac:n1z:ja:create_2.jpg?800 |}}

<note tip>At this stage the solution will be created including the project with the C++ program template.</note>

==== Adding the assembly part to the solution ====

To add a library written in assembler to our solution, we add a new project to the solution. Right-click on the solution and select add new project.

{{ :pl:edu:zmitac:n1z:ja:add_asm_1.jpg?800 |}}

{{ :pl:edu:zmitac:n1z:ja:add_asm_2.jpg?800 |}}

We create our new assembler project as a C++ compatible library project, running under the Windows operating system. From the list of available options, we select the Dynamic-Link Library (DLL).

{{ :pl:edu:zmitac:n1z:ja:add_step3.jpg?800 |}}

We name the project e.g. "JaAsm" and create it leaving the default path.

{{ :pl:edu:zmitac:n1z:ja:add_step4.jpg?800 |}}

<note tip>Both parts of our solution will be placed as subfolders in one folder named according to the name of the solution, in our case "Lab2_dll_cpp". Each of these subfolders will take the name of the respective projects, i.e. "Lab2_dll_cpp" for the part written in C++ and "JaAsm" for the part written in assembler.</note>

==== Setting dependencies in the solution ====
The next step is to set up the project dependencies so that compiling the C++ console application automatically forces the assembly library to be compiled. To do this, right-click on the C++ console project, select the "Build dependencies" menu, and then select "Project dependencies".

{{ :pl:edu:zmitac:n1z:ja:lab2_dependencies_1.jpg?800 |}}

{{ :pl:edu:zmitac:n1z:ja:lab2_dependencies_2.jpg?800 |}}

In the newly opened window, select our "JaAsm" library and click "OK".

{{ :pl:edu:zmitac:n1z:ja:lab2_dependencies_3.jpg?800 |}}

<note tip>Once this dependency is set, when you compile a project or program written in C++, the assembler file will also be recompiled automatically.</note>

==== Changing the type from a C++ library to an assembler one ====
First, you need to remove the automatically created C++ project files. To do this, simply select the header and source files, then right-click and choose "Remove" or click Delete key.

{{ :pl:edu:zmitac:n1z:ja:prepare_step1.jpg?800 |}}

For the library, it is necessary to customize the compilation as an MASM assembler file. To do this, right-click the library project and select "Build dependencies" from the list, then "Build customization".

{{ :pl:edu:zmitac:n1z:ja:prepare_step2.jpg?800 |}}

{{ :pl:edu:zmitac:n1z:ja:prepare_step3.jpg?800 |}}

In the newly opened window, select "masm" and confirm our selection with "OK".

{{ :pl:edu:zmitac:n1z:ja:prepare_step4.jpg?800 |}}

The next step is to add the source files in the assembler and the definition file to the library. To do this, right-click on the "JaAsm" library again, then select "Add" and "New item".

{{ :pl:edu:zmitac:n1z:ja:prepare_step5.jpg?800 |}}

We repeat this operation twice, each time selecting "Utility" and the text file type, giving the names: "JaDll.asm" and "JaDll.def".

{{ :pl:edu:zmitac:n1z:ja:prepare_step6.jpg?800 |}}

<note tip>If you perform the activities in the order given above, it is highly likely that the step shown in the next figure will not be necessary.</note>

In order for the compiler to know that the created assembler file is associated with MASM, its type must be indicated. This step is necessary when we use a C++ source file and only change its extension to *.asm. By clicking the work key on the *.asm file, we select properties and set the file type to Microsoft Macro Assembler.

{{ :pl:edu:zmitac:n1z:ja:file_type1.jpg?800 |}}


==== Setting the compilation mode ====

Compilation should be done in 64-bit mode (x64). To do this, set this mode in the solution options. Right-click on our solution and select "Properties".

{{ :pl:edu:zmitac:n1z:ja:x64_step1.jpg?800 |}}

{{ :pl:edu:zmitac:n1z:ja:x64_step2.jpg?800 |}}

In the newly opened window, go to the "Configuration properties" -> "Configuration" tab and then click "Configuration manager".

{{ :pl:edu:zmitac:n1z:ja:x64_step3.jpg?800 |}}

In the new window, we indicate the x64 platform everywhere (if a given option is unavailable, we select "New" from the available list, and then create the x64 platform by copying the settings from Any CPU). You should also enable compilation (Build) for both parts of the solution.

{{ :pl:edu:zmitac:n1z:ja:x64_step4.jpg?800 |}}

{{ :pl:edu:zmitac:n1z:ja:x64_step5.jpg?800 |}}

{{ :pl:edu:zmitac:n1z:ja:x64_step6.jpg?800 |}}

After that, we make sure once again that the platform indicated everywhere is x64 and close the window. The "x64" option should automatically be set in the main menu bar of Visual Studio, but it is worth checking and modifying it if necessary.

{{ :pl:edu:zmitac:n1z:ja:x64_step7.jpg?800 |}}

==== Final setup of the assembly library ====

We proceed to configure the library. To do this, right-click on the library and select "Properties".

{{ :pl:edu:zmitac:n1z:ja:config_dll_step1.jpg?800 |}}

{{ :pl:edu:zmitac:n1z:ja:config_dll_step2.jpg?800 |}}

In the newly opened window, go to "Linker" -> "Input" and in the "Module definition file" field, enter the name of our file "*.def". In our case, "JaDll.def". Confirm the entry.

{{ :pl:edu:zmitac:n1z:ja:config_dll_step3.jpg?800 |}}

The final step in the configuration is to disable the library entry point. To do this, go to the "Linker" tab and select "Advanced" and select "Yes (/NOENTRY)" in the "No entry point" field. Save the settings and close the window.

{{ :pl:edu:zmitac:n1z:ja:config_dll_step4.jpg?800 |}}

<note tip>A dll library, unlike a main program, does not have a starting point (address) that the operating system uses to start the program. It only provides a set of functions for other programs.</note>

===== Using a dll library written in assembler =====
==== dll library written in assembler ====

The dll library contains functions that can be used in other programs. The first version of our library will provide one function that returns a constant value. We will then read this value in a C++ file. An example of the assembly file (JaDll.asm) may look like this.

<code>
.code
MyProc proc
mov RAX, 2021
ret
MyProc endp
end
</code>

The program code file is inextricably linked to the definition file (JaDll.def). Such a file must contain the name of the DLL library as an argument of the LIBRARY directive, and a list of function names available to other modules preceded by the EXPORTS directive. In order for our MyProc function to be seen by the C++ program, we must declare it as exported. The JaDll.def file in our project may look like this.

<code>
LIBRARY JaAsm
EXPORTS MyProc
</code>

We often want to use the parameters passed to the function. Recall that in the 64-bit calling convention, the first four parameters are placed directly in the processor registers. The details were provided during lectures and are described in the instructions for the first lab exercise. Thus, two integer-type parameters are placed in the RCX and RDX registers. A function that returns the sum of two integer arguments would look like this.

<code>
...
MyProc proc
mov RAX, RCX
add RAX, RDX
ret
MyProc endp
...
</code>

Floating point arguments should be passed through registers XMM0 and XMM1, and the result should be returned through XMM0. Of course, the MMX/SSE extension instructions should be used.

<code>
...
FloatProc PROC
addsd xmm0, xmm1
ret
FloatProc ENDP
...
</code>
==== Calling functions in dll from C++ program ====

In order for a program written in C++ to use a function from a library, several steps must be performed.
- Prepare the type of the function that is compatible with its later call,
- Load the library using the LoadLibrary function while obtaining its handle,
- Read the current address of the function of interest to us by calling GetProcAddress,
- Use the function by referring to its address.
The sample code could look like this:

<code>
#include <windows.h>
#include <iostream>
typedef int(_stdcall* MyProc)();
HINSTANCE dllHandle = NULL;

int main()
{
    dllHandle = LoadLibrary(TEXT("JaAsm.dll"));
    MyProc procedura = (MyProc)GetProcAddress(dllHandle, "MyProc");
    std::cout << procedura();
}
</code>

Using a function with parameters requires slightly modified type definitions. You should also pay attention to the type of the value returned by the function. Remember that in the case of floating-point numbers, the size of the XMM0, XMM1 registers is 64 bits. This corresponds to a double-precision floating-point value, or in C++ to the type "double".

<code>
...
typedef int(_stdcall* MyProc)(int, int);
typedef double(_stdcall* FloatProc)(double, double);
...
</code>

==== Task to be completed in the laboratory ====
You should write a DLL in assembler and a C++ program that demonstrates how the DLL works.\\
**The DLL** should provide functions that perform and return the result of basic arithmetic calculations (addition, subtraction, multiplication, and division) on pairs of numbers passed as parameters to their call. The functions should have fixed- and floating-point versions (eight functions in total).\\
**The C++ program** should call all functions, pass sample parameter values, and display the results on the screen. No input user interface is required - the values for calculations can be placed in the program code.

==== For the report ====
Include the code of your C++ file and assembler source file WITH COMMENTS. Also, add a screenshot of the window with the results displayed.