DUT serial console access

Overview

Definition of API for communicating with DUT via serial console. More…

// typedefs

typedef struct tapi_serial tapi_serial;
typedef tapi_serial* tapi_serial_handle;

// structs

struct tapi_serial;

// global functions

te_errno tapi_serial_open_rpcs(rcf_rpc_server* rpcs, const char* console_name, tapi_serial_handle* p_handle);
te_errno tapi_serial_close(tapi_serial_handle handle);
te_errno tapi_serial_force_rw(tapi_serial_handle handle);
te_errno tapi_serial_spy(tapi_serial_handle handle);
te_errno tapi_serial_send_str(tapi_serial_handle handle, const char* fmt, ...);
te_errno te_errno tapi_serial_send_cmd(tapi_serial_handle handle, const char* fmt, ...);
te_errno te_errno te_errno tapi_serial_send_enter(tapi_serial_handle handle);
te_errno tapi_serial_send_ctrl_c(tapi_serial_handle handle);
te_errno tapi_serial_flush(tapi_serial_handle handle, size_t amount);
te_errno tapi_serial_read(tapi_serial_handle handle, char* buffer, size_t* buffer_len, int timeout_ms);
te_errno tapi_serial_check_pattern(tapi_serial_handle handle, int* offset, const char* fmt, ...);
te_errno te_errno tapi_serial_wait_pattern(tapi_serial_handle handle, int* offset, int timeout_ms, const char* fmt, ...);

// macros

#define TAPI_SERIAL_DEFAULT_USER

Detailed Documentation

Definition of API for communicating with DUT via serial console.

Copyright (C) 2018-2022 OKTET Labs Ltd. All rights reserved.

Typedefs

typedef struct tapi_serial tapi_serial

Session data. It’s assumed that the structure may contain TA name, RPC server handle, file descriptor of the session.

typedef tapi_serial* tapi_serial_handle

Session handle

Global Functions

te_errno tapi_serial_open_rpcs(rcf_rpc_server* rpcs, const char* console_name, tapi_serial_handle* p_handle)

Open new serial console session using existing RPC server on the Test Agent that serves DUT console.

Parameters:

rpcs	RPC server
console_name	Console name in Configurator tree
p_handle	New session handle location

Returns:

Status code.

te_errno tapi_serial_close(tapi_serial_handle handle)

Close serial console session.

Parameters:

handle

Session handle

Returns:

Status code.

te_errno tapi_serial_force_rw(tapi_serial_handle handle)

Force rw access to the console.

Parameters:

handle

Session handle

Returns:

Status code.

te_errno tapi_serial_spy(tapi_serial_handle handle)

Disable rw access to the console.

Parameters:

handle

Session handle

Returns:

Status code.

te_errno tapi_serial_send_str(tapi_serial_handle handle, const char* fmt, ...)

Write string to the console (without LF at the end).

Parameters:

handle	Session handle
fmt	printf-like format for the string

Returns:

Status code.

te_errno te_errno tapi_serial_send_cmd(tapi_serial_handle handle, const char* fmt, ...)

Send command and “Enter” (LF) to the console.

Parameters:

handle	Session handle
fmt	printf-like format for the command

Returns:

Status code.

te_errno te_errno te_errno tapi_serial_send_enter(tapi_serial_handle handle)

Send “Enter” (LF) to the console.

Parameters:

handle

Session handle

Returns:

Status code.

te_errno tapi_serial_send_ctrl_c(tapi_serial_handle handle)

Send “Ctrl+C” (break) to the console.

Parameters:

handle

Session handle

Returns:

Status code.

te_errno tapi_serial_flush(tapi_serial_handle handle, size_t amount)

Flush console session input buffer on the Test Agent (data is dropped).

Parameters:

handle	Session handle
amount	Amount of data to drop or 0 to drop all

Returns:

Status code.

te_errno tapi_serial_read(tapi_serial_handle handle, char* buffer, size_t* buffer_len, int timeout_ms)

Read data from the console. Note, that '\0' is not put to the buffer after data.

Parameters:

handle	Session handle
buffer	Input buffer
buffer_len	On input: buffer length; on output: length of data written
timeout_ms	Timeout of the operation in milliseconds, -1 to block until data are received or error occurs

Returns:

Status code.

te_errno tapi_serial_check_pattern(tapi_serial_handle handle, int* offset, const char* fmt, ...)

Check that data matching specified pattern (regular expression) are located in console session input buffer on the Test Agent. The data may be read after that by tapi_serial_read()

Parameters:

handle	Session handle
offset	If not NULL, is filled by offset of the first match
fmt	printf-like format for the pattern

Returns:

Status code.

te_errno te_errno tapi_serial_wait_pattern(tapi_serial_handle handle, int* offset, int timeout_ms, const char* fmt, ...)

Wait until data matching specified pattern (regular expression) appear in console session input buffer on the Test Agent. The data may be read after that by tapi_serial_read()

Parameters:

handle	Session handle
offset	If not NULL, is filled by offset of the first match
timeout_ms	Timeout of the operation in milliseconds
fmt	printf-like format for the pattern

Returns:

Status code.

Macros

#define TAPI_SERIAL_DEFAULT_USER

Default console user