nk-gen-c

The NK compiler (nk-gen-c) generates transport code based on the IDL, CDL, and EDL descriptions.

The nk-gen-c compiler receives the IDL, CDL or EDL file and creates the following files:

• A *.*dl.h file containing the transport code.
• A *.*dl.nk.d file that lists the created *.*dl.h file's dependencies on the IDL and CDL files. The *.*dl.nk.d file is created for the build system.

Syntax of the shell command for starting the nk-gen-c compiler:

nk-gen-c [-I <PATH>]... [-o <PATH>] [--types] [--interface] [--endpoints]

[--client] [--server] [--extended-errors] [--trace-client-ipc {headers|dump}]

[--trace-server-ipc {headers|dump}] [--ipc-trace-method-filter <METHOD>[,METHOD]...]

[-h|--help] [--version] <FILE>

Basic parameters:

• FILE

  Path to the IDL, CDL, or EDL file for which you need to generate transport code.

• -I <PATH>

  These parameters are used to define the paths to directories containing the auxiliary files required for generating transport code. (The auxiliary files are located in the sysroot-*-kos/include directory from the KasperskyOS SDK.) These parameters can also be used to define the paths to directories containing IDL and CDL files that are referenced by the file defined via the FILE parameter.

• -o <PATH>

  Path to an existing directory where the created files will be placed. If this parameter is not specified, the created files will be put into the current directory.

• -h|--help

  Prints the Help text.

• --version

  Prints the version of the nk-gen-c compiler.

• --extended-errors

  This parameter provides the capability to use interface methods with one or more error parameters of user-defined IDL types. (The client works with error parameters like it works with output parameters.)

  If the --extended-errors parameter is not specified, you can use interface methods only with one status error parameter of the IDL type UInt16 whose value is passed to the client via return code of the interface method. This mechanism is obsolete and will no longer be supported in the future, so you are advised to always specify the --extended-errors parameter.

Selective generation of transport code

To reduce the volume of generated transport code, you can use flags for selective generation of transport code. For example, you can use the --server flag for programs that implement endpoints, and use the --client flag for programs that utilize the endpoints.

If no selective generation flag for transport code is specified, the nk-gen-c compiler generates transport code with all possible methods and types for the defined IDL, CDL, or EDL file.

Flags for selective generation of transport code for an IDL file:

• --types

  The transport code includes the types corresponding to the IDL types from the defined IDL file, and the types corresponding to this file's imported IDL types that are used in IDL types of the defined IDL file. However, the types corresponding to imported IDL constants and to the aliases of imported IDL types are not included in the *.idl.h file. To use the types corresponding to imported IDL constants and to the aliases of imported IDL types, you must separately generate the transport code for the IDL files from which you are importing.

• --interface

  The transport code corresponds to the --types flag, and includes the types of structures of the constant part of IPC requests and IPC responses for interface methods whose signatures are specified in the defined IDL file. In addition, the transport code contains constants indicating the sizes of IPC message arenas.

• --client

  The transport code corresponds to the --interface flag, and includes the proxy object type, proxy object initialization method, and the interface methods specified in the defined IDL file.

• --server

  The transport code corresponds to the --interface flag, and includes the types and dispatcher (dispatch method) used to process IPC requests corresponding to the interface methods specified in the defined IDL file.

Flags for selective generation of transport code for a CDL or EDL file:

• --types

  The transport code includes the types corresponding to the IDL types that are used in the method parameters of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file).

• --endpoints

  The transport code corresponds to the --types flag, and includes the types of structures of the constant part of IPC requests and IPC responses for the methods of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file). In addition, the transport code contains constants indicating the sizes of IPC message arenas.

• --client

  The transport code corresponds to the --types flag, and includes the types of structures of the constant part of IPC requests and IPC responses for the methods of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file). In addition, the transport code contains constants indicating the sizes of IPC message arenas, and the proxy object types, proxy object initialization methods, and methods of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file).

• --server

  The transport code corresponds to the --types flag, and includes the types and dispatchers (dispatch methods) used to process IPC requests corresponding to the endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file). In addition, the transport code contains constants indicating the sizes of IPC message arenas, and the stub types, stub initialization methods, and the types of structures of the constant part of IPC requests and IPC responses for the methods of endpoints provided by the component (for the defined CDL file) or process class (for the defined EDL file).

Printing diagnostic information about sending and receiving IPC messages

Transport code can generate diagnostic information about sending and receiving IPC messages and print this data via standard error. To generate transport code with these capabilities, use the following parameters:

• --trace-client-ipc {headers|dump}

  The code for printing diagnostic information is executed directly before the Call() system call is executed and immediately after it is executed. If the headers value is specified, the diagnostic information includes the endpoint method ID (MID), the endpoint ID (RIID), the size of the constant part of the IPC message (in bytes), the contents of the IPC message arena handle, the size of the IPC message arena (in bytes), and the size of the utilized part of the IPC message arena (in bytes). If the dump value is specified, the diagnostic information additionally includes the contents of the constant part and arena of the IPC message in hexadecimal format.

  When using this parameter, you must either specify the selective generation flag for transport code --client or refrain from specifying a selective generation flag for transport code.

• --trace-server-ipc {headers|dump}

  The code for printing diagnostic information is executed directly before calling the function that implements the interface method, and immediately after the completion of this function. In other words, it is executed when the dispatcher (dispatch method) is called in the interval between execution of the Recv() and Reply() system calls. If the headers value is specified, the diagnostic information includes the endpoint method ID (MID), the endpoint ID (RIID), the size of the constant part of the IPC message (in bytes), the contents of the IPC message arena handle, the size of the IPC message arena (in bytes), and the size of the utilized part of the IPC message arena (in bytes). If the dump value is specified, the diagnostic information additionally includes the contents of the constant part and arena of the IPC message in hexadecimal format.

  When using this parameter, you must either specify the selective generation flag for transport code --server or refrain from specifying a selective generation flag for transport code.

• --ipc-trace-method-filter <METHOD>[,METHOD]...

  Diagnostic information is printed if only the defined interface methods are called. For the METHOD value, you can use the interface method name or the construct <package name>:<interface method name>. The package name and interface method name are specified in the IDL file.

  If this parameter is not specified, diagnostic information is printed when any interface method is called.

  This parameter can be specified multiple times. For example, you can specify all required interface methods in one parameter or specify each required interface method in a separate parameter.