1

TRX SDK

Version: 2023-06-08
 i

Table of Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 IQ samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

3 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1 RX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.2 TX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

4 Timestamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

5 API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

6 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

7 Optimizations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

8 Remote API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.1 Receive messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
8.2 Send messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
 1

1 Introduction
Here is how to implement a Amarisoft eNB/UE driver to communicate with a radio equipment
and exchange IQ samples.
It consists in providing to eNB software a shared library where specific callbacks will be imple-
mented.
You will find an example driver (trx example.c) to start developing your driver and Makefile to
compile it.

This driver may be implemented in any language. It must respect the standard C API
provided as trx_driver.h
The driver will be launched in user mode.
 2

2 IQ samples
Amarisoft IQ are coded with 32 bits float type and have following range:
-1.0 <= IQ <= 1.0
It is up to you to adapt level to your specific needs.
As it may require a lot of CPU time, SSE optimized sample code is provided (See [Optimiza-
tions], page 6) to help you.

Gain of uplink IQ is direclty handled by eNB software so no specific treatment is needed.

 3

3 Callbacks
Two main callbacks are set to exchange IQ: one for reading and another one for writing.

3.1 RX
Reading process is clock master:
• The read callback (trx_read_func) is called regularly to get IQ samples.
• It has to block until at least 1 sample is available and must return at most count samples.
• The count argument value depends on sample rate and is at most 4096 samples.
• The callback provides clock information using "ptimestamp" pointer.
It must be expressed in samples so that time can be retrieved by stack using sample rate.
The timestamp wil be used by stack to provide send time to write process.

3.2 TX
• The write callback (trx_write_func) is called regularly and timestamp information is
direclty calculated from reading process.
• This timestamp information represents when the radio head must send samples to the air.
It is important to be as precise as possible to keep synchronization between TX and RX.
• The count argument that represent number of samples to send can be configured by im-
plementing with trx_get_tx_samples_per_packet_func callback.
Else, the stack will estimate this value depending on sample rate
• If samples pointer is NULL, this means TX has to be disabled (must not transmit anything)
during the time represented by count parameter. The flag TRX_WRITE_FLAG_PADDING will
be also set. This case only happens in TDD mode.
• The write callback must be as fast as possible.
 4

4 Timestamps
Timestamp unit is sample, and is used to convert to time depending on sample rate provided:
<time> = <timestamp> / <sample_rate>
Note that timestamps provided by trx_read API will be used by stack to generate a clock.
This is the only clock the stack will use: it does not rely on PC clock are any network or
hardware component.
As a result, there is no constraints on the speed of IQ sample feeding. It does not have to be
real time or linear.
You can even pause the system and resume it later to interface with non real time components.
 5

5 API
Amarisoft driver API is located in trx driver.h.
 6

6 Example
A dummy driver example is implemented in trx_example.c.
trx_example is a dummy transceiver driver for the Amarisoft LTE eNodeB. It simulates
zero samples coming from a source synchronized to the PC clock and optionally outputs the
maximum amplitude of the downlink I/Q samples.
You can compile the trx example driver by just typing make.
Then copy trx_example.so to the lteenb directory.
You can enable it with the following property in the eNodeB configuration:
//include "rf_driver/[Link]",

rf_driver: {
name: "example",
dump_max: 1, /* enable maximum amplitude output */
},
tx_gain: 0,
rx_gain: 0,
sample_rate: 11.52, /* set the sample rate to 11.52 MHz */
 7

7 Optimizations
For fast IQ samples convertion, optimized routine are available in convert16_see.c.
This is a example code of fixed point/floating point numbers optimized with SSE instructions.
This file must be compiled with "-msse4.1" gcc option
For more information on Intel SSE/AVX: https: / / software . intel . com / sites /
landingpage/IntrinsicsGuide/
 8

8 Remote API
Since version 14 of API you can receive and send messages via remote API.
Please refer to the remote API section of your software component for usage.
trx_msg_recv_func can be called from a different thread than read and write functions.
TRXMsg API is thread safe.

8.1 Receive messages

All trx messages will be sent to trx_msg_recv_func.
Use TRXMsg->get_double and TRXMsg->get_string API to get data from incoming message.
Use TRXMsg->set_double and TRXMsg->set_string API to set data for response.

Then use TRXMsg->send API when your response is ready to be sent.

If you need to send response later, use TRXMsg->set_timeout API, then call TRXMsg->send
API when your response is ready to be sent.
The timeout_cb will be called when timeout occurs. You need to call TRXMsg->send to free
resources.

8.2 Send messages

To send a message, call trx_msg_send_func.
This will create a message that you can populate with TRXMsg->set_double and TRXMsg->set_
string API.
Then call TRXMsg->send API to send your message.
The message type will be trx and the client must register to this type of message to receive
it.