MICROSOFT RESEARCH The Sora Manual The Microsoft Research Software Radio (Sora) Project The Sora Core Team (Ver 1.7) August, 2012 The Microsoft Research Software Radio (Sora) Project is an initiative from the Wireless and Network Group, Microsoft Research Asia.
1
Contents Chapter 1. Introduction ............................................................................................................. 8 1.1 What’s new in Sora SDK ver 1.7?..................................................................................... 9 1.2 What’s new in Sora SDK ver 1.6?..................................................................................... 9 1.3 What’s new in Sora SDK ver 1.5?...............................................................................
3.2 Abstract Radio and Radio Object................................................................................... 31 3.2.1 Radio Allocation and Release ................................................................................ 33 3.2.2 Radio Configuration and Start ............................................................................... 33 3.2.3 Radio example ....................................................................................................... 33 3.
7.4 Sample: UMXDot11 ....................................................................................................... 57 Chapter 8. UMX Reflection ...................................................................................................... 59 8.1 UMX Reflection Operations ........................................................................................... 59 8.2 UMXSDRab – a user-mode SDR modem .......................................................................
9.4.17 hmin ....................................................................................................................... 68 9.4.18 insert ...................................................................................................................... 68 9.4.19 interleave_high ...................................................................................................... 69 9.4.20 interleave_low ...................................................................................
9.4.42 saturated_sub........................................................................................................ 75 9.4.43 set_all .................................................................................................................... 75 9.4.44 set_all_bits............................................................................................................. 75 9.4.45 set_zero ..............................................................................................
Chapter 11. 11.1 Tools and Utilities .................................................................................................. 84 dut tool .......................................................................................................................... 84 11.1.1 Using dut to configure the HwTest driver ............................................................. 84 11.1.2 Using dut to transmit a signal ................................................................................
Chapter 1. Introduction The Sora manual provides reference documentation for Microsoft Research Software Radio, also known as Sora, which is a research project initiated in the Wireless and Networking Group (WNG) at Microsoft Research Asia. Sora is a high-performance fully programmable software radio based on general purpose processors (i.e., CPU) in commodity PC architecture. Sora contains both hardware and software components.
1.1 What’s new in Sora SDK ver 1.7? The new Sora SDK ver 1.7 supports 64-bits Windows 7. So it now makes full use of the most powerful operating system capability from Microsoft. Some information you need to know before using Sora SDK ver 1.7: Driver Test-Signing. The 64-bit drivers must be signed before installed on Windows 7. The driver binary shipped with the SDK package is already signed. Set Windows 7 to testing mode to support test-signed driver.
UMXSDRab. UMXSDRab is a powerful SDR 802.11 modem based on UMX reflection. It supports both client mode and adhoc mode. So it can easily connect to a commercial 802.11 AP or device. UMXSDRab has an easy-to-use interactive interface to configure and monitor the status of SDR modem application. DbgPlot tool. DbgPlot is a versatile tool that allows a program to dynamically generate various graphics in real-time. It is a very useful tool for real-time monitoring or debugging DSP programs. 1.
1.4 Target Operating Systems Sora works on Microsoft Windows operating system. After Sora SDK ver 1.7, Sora is able to work on Microsoft Windows XP (32bit) with Service Pack 3 and Microsoft Windows 7 (64bit). Sora also requires Microsoft Windows Driver Kit (WDK) to be compiled. You can download WDK from Microsoft downloads (http://www.microsoft.com/whdc/DevTools/WDK/WDKpkg.mspx). 1.
Table 1. Hardware requirements for the Microsoft research Software Radio CPU/Freq Memory PCIe-x8/x16 slot Hard Disk Radio hardware quad-core/2.
Chapter 2. Getting Started 2.1 Install Sora SDK After you download the Sora SDK package, you can simply run SoraSDK.msi and follow the onscreen instructions to install software. The Sora SDK package contains the following components: The Sora core driver for the RCB. The HwTest driver - implementing user-mode extension. UMXSDRab – an 802.11 SDR modem based on UMX Reflection The sample SoftWiFi driver – a kernel-mode miniport driver implementing full functional IEEE 802.11a/b/g.
2. Execute bcdedit /set TESTSIGNING ON 3. Execute bcdedit for confirmation 4.
Now, the target system is ready for installing 64-bit PCIE, HWTest and SDRMiniport test-signed drivers. 2.2.2 Installation Progress Before you install the RCB driver, please make sure that the RCB board is firmly plugged into your motherboard and a RF front-end is properly connected to the RCB. Please follow the instructions in "Sora Device Drivers Installation.pdf" to install and configure the RCB driver. Then, you can install the HwTest driver.
Sora SDK includes a handy tool for testing your hardware: the Hardware Verification Tool (HVT). HVT allows you to visually verify your RF hardware and tune proper parameter settings (like central frequency offset and Tx/Rx gains). You need two Sora boxes to run HVT, one as the sender and the other as the receiver. Before starting HVT, you should make sure both the RCB driver and the HwTest driver are enabled. Once you start HVT ( HwVeri.
Table 2 provides a reference to each element on the HVT main window. u t s r q p a o n b c d e m l f g k h i j Figure 2. The main window of HVT.
Table 2. HVT Reference. Label a b c Name Test method selection Start button Dump button d Suggestion button e Auto calibration button DC value Central Frequency Offset I/Q imbalance f g h i q Signal-to-Noise Ratio (SNR) Status bar Log window Save log button Clear button Save parameter button Load button AGC enable/disable RxPa selection r s t Sampling rate Central Frequency Gain adjustment u Mode selection j k l m n o p Remark Select test type (sine test/SNR test). Start/stop a test.
sender and receiver radio, and reveal the best receiver gain setting. To perform a since test, you can follow the steps listed below: 1. Run HVT on two Sora boxes. Select “sine test” at both machines. 2. Configure one as the sender and the other as the receiver. 3. Select the sampling rate at the receiver that matches your RAB sampling rate. 4. Click “start” at the sender. You may notice the sender’s status bar displays the message “Sending 1MHz sine wave”. 5. Click “start” at the receiver.
Figure 4. Received signal from the SNR test. 2.3.2 Receiving frames from a commercial WiFi card If you have only a single set of Sora machine, you can use it as the receiver and use a laptop with WiFi interface as the sender. The laptop should support flexible WiFi configurations (e.g., Atheros NIC with MadWiFi driver) because you will need to set it to ad hoc mode with SSID “sdr” at channel 3 (by default, the HwTest driver configures the RF front-end to channel 3).
To view dumped OFDM signals (802.11g rates of 6Mbps ~ 54Mbps) with sdscope-11a, you should also specify the sampling rate of the RAB with following command lines, sdscope-11a.exe -s40 ## If your RAB’s sampling rate is 40MSps or, sdscope-11a.exe -s44 ## If your RAB’s sampling rate is 44MSps Figure 5. Displaying the dump file with sdscope-11b. 2.4 2.4.
The installer of Sora SDK package has created four shortcuts to build command window in the start-menu (located in Start\Programs\Microsoft Research Asia\ Software Radio Academic Kit 1.7). Before you can use them, you should configure the WDK path by adding an environment variable, WINDDK_ROOT. This variable should point to the root path of the WDK. Environment variables are configured using Windows Control Panel. Figure 6 shows a screen snapshot when you add a new environment variable on Windows XP.
2.4.2 Driver Test-Signing The Test-Signing is required after successfully built the 64-bit Windows 7 drivers. All the tools used for Test-Signing are released in WDK. Start a build environment command prompt of WDK and follow the steps listed below to acoomplish the process. 1. Create a MakeCert test certificate. A MakeCert test certificate is required first and is used as certificate for digitally signing.
There are still other ways to sign drivers. We just provide 1 here. Please refer the WDK help documentation for more detail and the parameters for each releated tools. 2.4.3 Install SoftWiFi Driver After you successfully build the SoftWiFi source, the driver binary is generated at %SORA_ROOT%\target\fre(chk)_wxp_x86\i386, where you can also find the corresponding inf file (sdr.inf). You can use “Add Hardware Wizard” to install them on Windows.
specified the same sampling rate in sdr.inf file as your RAB. Chapter 2.4.4 lists all configurations to the SoftWiFi driver. 2.4.4 Configure the SoftWiFi driver The sample SoftWiFi driver can be configured by editing entries in sdr.inf file. Table 3. Configuration with SDR.INF. Entry Name NetworkAddress Description MAC address Type String BSSID Basic service set identification String ModMode Protocol of modulation and demodulation Data rate in Mbps in 802.
2.5 Directory Structure The directory structure shown here assumes the Sora SDK is installed at d:\SORASDK1.7 D:\SORASDK1.7 │ │ │ │ AcademicKit-LA.pdf MSR-LA.pdf Sample Code-LA.pdf Readme.htm Agreement to purchase the academic kit MSR License agreement MSR License agreement for the sample source code The ReadMe file ├─bin | | dbgplot.exe │ │ dut.exe │ │ dot11config.exe │ │ demod11.exe │ │ HwVeri.exe | | umxsdrab.exe │ │ UMXDot11.exe │ │ sdscope-11a.exe │ │ sdscope-11b.exe │ │ SrView.
│ │ IntFiltr.reg │ │ IntFiltr.sys │ │ IntFiltrCmd.
Chapter 3. Sora Fundamentals 3.1 Architecture The overall system architecture of Sora is illustrated in Figure 7. The RCB interconnects RF frontends to the PC. The RCB talks to the PC using the PCI-E interface, and with read/write digital signal samples from/to PC memory using direct memory access (DMA). It connects to the RF front-end boards with the Sora Fast Radio Link (SoraFRL). SoraFRL defines the necessary protocol for the RCB to control the RF boards.
802.11a/b/g protocol. Alternatively, one can write user-mode SDR application programs that interact with RCB/RF hardware through Sora User-Mode Extension API (UMX API). Sora SDK provides a set of highly optimized UMX API to facilitate high performance and low latency DSP implementation in user-mode, including exclusive thread library, zero-copy sample transport and integration with network stack.
processing. The basic routines that need to be implemented are modulation, demodulation and channel monitoring (carrier sensing). For ease of cross-reference, a global context, called SDR_CONTEXT, is used in the sample SoftWiFi driver to pass data across different layers. This SDR_CONTEXT also contains pointers to other useful data structures and is used as the sole parameter for many routines in the SoftWiFi driver.
3.2 Abstract Radio and Radio Object An Abstract Radio (AR) is a software abstract of radio hardware. An abstract radio contains a Tx channel, a Rx channel, and a set of control registers. A SDR application – either a SDR miniport driver or a UMX-based user-mode program – is operating on abstract radio objects (ARO). The RCB driver and hardware map every ARO to a real RF front-end. Figure 10 illustrates the Abstract Radio architecture.
end. The TX sample buffer is initialized at the beginning and is a shared resource. Therefore, when the SDR driver uses multiple threads for modulation, the access to the TX sample buffer from different threads should be properly coordinated by __TxBufLock. The RCB hardware may also send PnP events to software. These PnP events may be passed to a SDR driver as well. In particular, two PnP events should be monitored for a SDR driver. They are: 1) Power management notification.
// RX_STREAM to access Rx queue DMA Buf SORA_RADIO_RX_STREAM __RxStream; ULONG volatile BOOLEAN __fCanWork; __fRxEnabled; // TX Channel - Tx Sample Buffer PTXSAMPLE __TxSampleBufVa; PHYSICAL_ADDRESS __TxSampleBufPa; ULONG __TxSampleBufSize; LONG __TxBufLock; // Lock to access the Tx sample buffer //FAST_MUTEX __ModSampleBufMutex; } SORA_RADIO, *PSORA_RADIO, **PPSORA_RADIO, __SORA_RADIO, *__PSORA_RADIO; Figure 11. Definition of the RADIO Object. 3.2.
break; } // Successfully allocate radio resource.. hRes = SoraRadioInitialize( RadioInPHY(pPhy, RADIO_RECV), // Get the radio in PHY list NULL, // reserved SAMPLE_BUFFER_SIZE, // buffer size for TX RX_BUFFER_SIZE); FAILED_BREAK(hRes); // Start radio hRes = SoraRadioStart( RadioInPHY(pPhy, RADIO_RECV), SORA_RADIO_DEFAULT_RX_GAIN, SORA_RADIO_DEFAULT_TX_GAIN, NULL); FAILED_BREAK(hRes); … return hRes; } Figure 12. Radio allocation and initialization. 3.
typedef struct __PACKET_BASE { PMDL pMdl; // memory descriptors for original packet data PTX_DESC pTxDesc; // Refers to TX channel of an Abstract Radio LONG fStatus; ULONG PacketSize; ULONG Reserved1; //for customized attachment ULONG Reserved2; //for customized attachment ULONG Reserved3; //for customized attachment ULONG Reserved4; //for customized attachment PVOID pReserved; } PACKET_BASE; Figure 13. Definition of PACKET_BASE ojbect.
re0 im0 re1 im1 rei imi Rei+1 imi+1 Figure 14. Structure of the TX sample buffer. Once the SDR driver gets the modulation sample buffer, it should immediately generate waveform samples from the packet data (modulation). The SDR application driver should call SoraPacketSetSignalLength to specify the size of the buffer that is actually filled with the waveform samples. The size MUST be a multiple of 128 bytes. Therefore, some padding may be needed to ensure this. 3.3.
do { … pRadio = RadioInPHY(pPhy, RADIO_SEND); do { // Try to dequeue a pending packet and do modulation SafeDequeue(pSendQueueManager, SendSrcWaitList, pTCB, DLCB); if (!pTCB) { break; } if (!DLCB_CONTAIN_VALID_PACKET(pTCB)) // invalid packet, pass through the pipeline { SafeEnqueue(pSendQueueManager, SendSymWaitList, pTCB); InterlockedIncrement(&pSendQueueManager->nSymPacket); InterlockedDecrement(&pSendQueueManager->nSrcPacket); continue; } // Allocate Tx Channel Resource for a packet if (IS_PACKET_NO_RES
Figure 15. Modulation and transfer.
} while (FALSE); SoraFSMGotoState(StateMachine, Dot11_MAC_CS); return; } Figure 16. Waveform transmission and cleanup. 3.4 Reception The RX channel of a radio is enabled by SORA_HW_ENABLE_RX. The SDR driver can read the RX channel through an RX_STREAM object. The SDR driver can obtain a RX_STREAM object by calling SoraRadioGetRxStream. The RX channel of a radio is organized as a stream of signal blocks. Each signal block contains an array of 28 complex I/Q samples.
RX_DESC (16 bytes) RX_BLOCK I0 Q0 I1 Q1 SignalBlock I 27 Q 27 16 bits 16 bits Figure 17. Structure of a signal block. 3.4.1 Example Figure 18 shows sample code to read from an RX_STREAM object. The full code can be found in bbb_spd.c. HRESULT BB11BSpd(PBB11B_SPD_CONTEXT pSpdContext, PSORA_RADIO_RX_STREAM pRxStream) { // ... FLAG touched; ULONG PeekBlockCount = 0; HRESULT hr = S_OK; SignalBlock block; do { // ...
pSpdContext->b_evalEnergy = BlockEnergySum[0]; hr = BB11B_OK_POWER_DETECTED; break; } if (touched && PeekBlockCount > pSpdContext->b_minDescCount) { hr = BB11B_CHANNEL_CLEAN; break; } if (PeekBlockCount >= pSpdContext->b_maxDescCount) { hr = BB11B_E_PD_LAG; break; } } } while(FALSE); // ... return hr; } Figure 18. Example code to read from RX_STREAM.
Chapter 4. MAC Programming Sora provides a utility library to program a Finite State Machine (FSM). An FSM is commonly used in the MAC and other protocol implementations. For example, Figure 19 shows a simplified MAC state-machine of 802.11 that contains three states: carrier sense, transmission (TX) and reception (RX). le D x R Rx e/ on D led Tx Fai P De owe tec r ted on e/ Fa i Carrier Sense d an g e i n re nd el F Pe nn Tx ha C d Channel Free Tx Figure 19.
In Sora, a state machine may usually run in an exclusive thread that provides real-time support. The SDR driver uses SORA_FSM_CONFIG to assign a parameter to the FSM instance, which will be passed to each state handler. This parameter is usually a pointer to SDR_CONTEXT. During initialization, one should also specify the initial state on which the FSM starts using SoraFSMSetInitialState. Figure 20 shows an excerpt from sdr_mac.h to declare the simplified 802.11 MAC FSM.
A call of SoraFSMStop from any state handler terminates the FSM. SoraFSMGotoState is called before exiting the current state handler to transit to other states. The state handler of the new state will be invoked by the FSM thread. 4.2.1 Example Figure 22 shows an example state handler from sdr_mac_cs.c for carrier sense. It enters different states based on the result of the PHY sensing function.
{ DbgPrint("[MAC_CS][Error] Ack detect fail, we don't need ACK anymore \n"); MAC_DISLIKE_ACK(pMac); } else { SoraFSMGotoState(StateMachine, Dot11_MAC_RX); return; } } DbgPrint("[MAC_CS] channel clean, goto tx \n"); SoraFSMGotoState(StateMachine, Dot11_MAC_TX); return; case BB11B_OK_POWER_DETECTED: SoraFSMGotoState(StateMachine, Dot11_MAC_RX); return; case E_FETCH_SIGNAL_HW_TIMEOUT: //Hardware error SoraFSMGotoState(StateMachine, Dot11_MAC_TX); DbgPrint("[Error] E_FETCH_SIGNAL_HW_TIMEOUT \n"); //InterlockedI
Chapter 5. Real-Time Support 5.1 Using Sora thread Sora supports real-time behavior via exclusive threading. An exclusive thread (or ethread) is a non-interruptible thread running on a multi-core system. In previous versions, an exclusive thread is bound to a dedicated CPU core and the programmer should manually assign CPU cores. Since Sora SDK version 1.5, the core assignment is performed by the library that dynamically allocates CPU cores to ethreads.
IN PPHY pPhy, IN PSDR_CONTEXT SDRContext, IN ULONG ulRadioNum) { … if (pPhy->PHYMode == DOT_11_A) { hRes = NDIS_STATUS_FAILURE; pPhy->Thread = SoraThreadAlloc(); if (pPhy->Thread) if (SoraThreadStart(pPhy->Thread, viterbi_proc, &pPhy->BBContextFor11A.
case 0x6: VitDesCRC18(pRxContextA); break; case 0x1: VitDesCRC24(pRxContextA); break; case 0x5: VitDesCRC36(pRxContextA); break; case 0x0: VitDesCRC48(pRxContextA); break; case 0x4: VitDesCRC54(pRxContextA); break; } _mm_mfence(); BB11A_VITERBIDONE_SET_EVENT(pRxContextA); } } Figure 24. Example ethread routine. 5.2 Interrupt affinity With ethread, the SDR application driver can prevent the task from being preempted by other threads. But the task may still be interrupted by hardware.
-a : Add interrupt affinity set filter driver -r : Remove interrupt affinity set filter driver -m affinity mask : Specify the affinity mask Figure 25. Help page of intfiltrcmd.exe. You can configure the interrupt affinity using intFiltrCmd.exe. Type intfiltrcmd, and you can see the help page shown in Figure 25. The default interrupt affinity is 0xFFFFFFFF, meaning all cores can be interrupted.
Chapter 6. Signal Cache One key design choice for the Sora system is to provide a large on-board memory on the RCB. This on-board memory can serve as a cache for pre-generated signals. The SDR driver can call SoraInitSignalCache to initialize a SIGNAL_CACHE structure. After initialization, a portion of the RCB memory is allocated to the signal cache and the SDR driver can store signals in it. The cache is organized into a number of equal size slots.
PHYSICAL_ADDRESS PhysicalAddressHigh = {0x80000000, 0}; NdisZeroMemory(pAckCacheMan, sizeof (ACK_CACHE_MAN)); //constructor NdisInitializeEvent(&pAckCacheMan->RemoveEvent); NdisAllocateSpinLock(&pAckCacheMan->ReqQueueLock); pAckCacheMan->pOwnerPhy = pOwnerPhy; do { hr = SoraInitSignalCache (&pAckCacheMan->AckCache, pRadio, MaxAckSize, MaxAckNum); FAILED_BREAK(hr); pAckCacheMan->pAckModulateBuffer = MmAllocateContiguousMemorySpecifyCache( MaxAckSize , PhysicalAddressLow, PhysicalAddressHigh, PhysicalAddres
PACK_CACHE_MAN pAckCacheMan = (PACK_CACHE_MAN)Context; MAC_ADDRESS MacAddr; PHY_FRAME_KEY Key; ULONG Length = 0; HRESULT hr; UNREFERENCED_PARAMETER(DeviceObject); MP_INC_REF(pAckCacheMan); do { int i; __Dequeue(pAckCacheMan, &MacAddr); Key.QuadKey.u.HighPart = 0; Key.QuadKey.u.LowPart = 0; for (i = 0; i < MAC_ADDRESS_LENGTH; i++) { Key.KeyBytes[i] = MacAddr.
Chapter 7. User-Mode Extension Sora provides a new programming model, called User-Mode eXtension (UMX), which allows user-mode applications to access the radio resources. With UMX APIs, developers can write baseband processing in user-mode, and therefore the programming and debugging efforts are greatly reduced. 7.1 UMX Initialization and Configuration UMX is based on the HWTest driver (see also Chapter 11. ), as shown in Figure 28. Figure 28. Architecture of Sora UMX.
Figure 29 shows the sample code that initializes and configures UMX.
void RxRoutine () { PVOID pRxBuf = NULL; ULONG nRxBufSize = 0; HRESULT hr; … SORA_RADIO_RX_STREAM SampleStream; // // Map Rx Buffer // hr = SoraURadioMapRxSampleBuf ( TARGET_RADIO, // radio id & pRxBuf, // mapped buffer pointer & nRxBufSize // size of mapped buffer ); if ( FAILED (hr) ) { printf ( "Error: Fail to map Rx buffer!\n" ); return; } printf ( "Mapped Rx buffer at %08x size %d\n", pRxBuf, nRxBufSize ); // Generate a sample stream from mapped Rx buffer SoraURadioAllocRxStream( &SampleStream, TARGET_
vi re, im; vcs s = pSamples[i]; s = shift_right (s, 3); conj_mul ( re, im, s, s ); // (a+bj) * (a-bj) sum = add (sum, re ); } sum = hadd (sum); // get a sum of the all element on the vector int energy = sum[0]; printf(" \r"); //clean the line. printf ( "%d --> Energy %10d \r", index++, energy / 1000); } } SoraURadioReleaseRxStream(&SampleStream, TARGET_RADIO); if (pRxBuf) { hr = SoraURadioUnmapRxSampleBuf (TARGET_RADIO, pRxBuf); } printf("Unmap hr:%08x\n", hr); } Figure 30.
SampleBuffer = SoraUAllocBuffer (SampleBufferSize); printf("alloc Tx Sample buffer ret: %08x\n", SampleBuffer); If (!SampleBuffer) break; ULONG TxID; ULONG SigLength = PrepareSamples(fname, (char*)SampleBuffer, SampleBufferSize); if (SigLength == 0) { printf("file access violation\n"); break; } // // First Allocate Tx Resource // The size should be a multiple of 128 // ALIGN_WITH_RCB_BUFFER_PADDING_ZERO(SampleBuffer, SigLength); hr = SoraURadioTransferEx (TARGET_RADIO, SampleBuffer, SigLength, &TxID); print
Command “umxdot11 rx” will launch umxdot11 in the receiving mode. Based on the configuration, the umxdot11 searches OFDM or DSSS signals. However, it tries to demodulate and decode frame with any valid rate. Command “umxdot11 tx” will put umxdot11 in sending mode. It will continuously send a random generated frame with the modulation method and the size specified in the configuration file. Note that you should use command “dut start” to enable the HwTest driver as well as the UMX library. ;; Protocol: 802.
Chapter 8. UMX Reflection Since Sora ver 1.6, a new mechanism, called UMX reflection, is supported. UMX reflection allows a user-mode SDR application (SDR modem) to be seamlessly integrated into Window’s network stack. Therefore, any network application can use the SDR modem to communicate in a wireless network. Figure 33 shows the architecture of UMX reflection. The HwTest driver acts as a virtual Ethernet card to the operating system.
handle to the frame. The SDR application should keep the handle until it finishs processing on the frame data. Then, it should return the handle to the HwTest driver by calling SoraUCompleteTxPacket. To insert a received frame into to the reception queue of the HwTest driver, the SDR application should call SoraUIndicateRxPacket. 8.2 UMXSDRab – a user-mode SDR modem UMXSDRab is a new UMX reflection SDR modem application. It supports both 802.
Figure 34. The interactive console of UMXSDRab. Parameter name -s [40|44] -f freq -r rate -b -o [0|1] -h Comments Specify the sampling rate of the underlying hardware. It should be either 40MHz or 44MHz. Please refer to your hardware specification. Specify the central frequency in, unit of MHz. For example, channel 3 in 2.4GHz band is centered at 2422MHz. Specify the initial modulation (sending) rate. The default uses the lowest rate.
a Toggle the auto configuration. [ Increase the modulation (sending) data rate. ] Decrease the modulation (sending) date rate. + Force to increate the rx gain. - Force to descrease the rx gain. c Associate to AP, only valid in client mode. p Switch umxsdrab mode between client and adhoc. Table 5. Commands for the interactive console.
Chapter 9. Vector1 Library Vector1 is a template library for SIMD programming since Sora SDK 1.1. Vector1 library provides new vector data types and vector operations to accelerate PHY signal processing. Vector1 provides a general vector abstraction that is rather independent from the real processor architecture. Therefore, it improves the portability of algorithms implemented using SIMD instructions.
vcq/vcuq vcf Complex Signed / Unsigned Quad Word 128b Complex Float 64b 1 2 Table 6. Vector1 Data Types. 9.2 Basic Operations The Vector1 library defines many operations on the vector types. The most common operations are arithmetic operations on vector types, including abs, abs0, add, conj, conj0, conj_mul, conj_mul_shift, conjre, mul_high, mul_j, mul_low, mul_shift, pairwise_muladd, hadd4, saturated_hadd4, hadd, saturated_hadd, saturated_add, saturated_pack, saturated_sub, and sign.
vmemcpy, vsqrnorm, vshift_right, vshift_left, vsum. An integer template argument of the class specialize the size of arrays. For example, the code snippet below copies consequent 11 vector data from a memory buffer (pointed by “pSpreadSig”) to another location (indicated by “pbuf” ). rep<11>::vmemcpy(pbuf, pSpreadSig ); Figure 36 Removing the DC component with Vector1. 9.4 Vector1 References The following sections explain each operation defined in current Vector1 Library.
Prototype: T abs0 (const T & a); Description: compute the actual element-wise absolute value of a vector. 9.4.3 add Vector type: T = vb/s/i/q/f/ub/us/ui/uq/cb/cs/ci/cq/cf/cub/cus/cui/cuq Prototype: T add(const T & a, const T & b); Description: compute the sum of two vectors 9.4.4 and Vector type: T = vb/s/i/f/ub/us/ui/cb/cs/ci/cf/cub/cus/cui Prototype: T and(const T & a, const T & b); Description: compute the logic bit-wise and of two vectors 9.4.
9.4.8 conj Prototype: vcs conj(const vcs & a); Description: compute an approximate conjugate of each complex number in a vector, using the “xor” operator for sign reversion. It is not accurate but has better performance. 9.4.9 conj0 Prototype: vcs conj0(const vcs & a); Description: Compute the accurate conjugate of each complex number in a vector. 9.4.
Prototype: T flip(const T& a); Description: Swap the real and imaginary parts of each complex number 9.4.15 hadd Vecotr type: T = vcs/vi/vui Prototype: T hadd (const T&a); Description: hadd returns a vector, each element of which contains the sum of all elements in the input parameter. 9.4.16 hmax Vector type: T = vb/s/ub/us Prototype: T hmax(const T& a); Description: Copy the largest element in the source vector to all elements of a vector128 type 9.4.
r0... and a0... are the sequentially ordered elements of return value r and parameter a. r0 and a0 are the least significant bits. 9.4.19 interleave_high Vector type: T = vb/s/i/q/ub/us/ui/uq/cb/cs/ci/cub/cus/cui Prototype: T interleave_high(const T& a, const T& b); Description: Interleave the elements in the higher half of the 2 source vectors to a resulting vector. The first source operand will be interleaved to the even indices, and the second source to the odd indices. 9.4.
Vector type: T = vb/s/i/q/ub/us/ui/uq/cb/cs/ci/cq/cub/cus/cui/cuq Prototype: void load(T& r, void* p); Description: Load 128-bit vector from the address p, which is not necessarily 16-byte aligned 9.4.
Prototype: T mul_low(const T& a, const T& b); Description: Element-wise multiplication, keeping only the lower half of the product 9.4.28 mul_shift Prototype: vcs mul_shift(const vcs& a, const vcs& b, int nbits_right); Description: Multiply and keep the low part product after right-shifting, i.e., return a * b >> nbits_right 9.4.29 or Vector type: T = vb/s/i/q/ub/us/ui/uq/cb/cs/ci/cq/cub/cus/cui/cuq Prototype: T or(const T& a, const T& b); Description: Bitwise OR 9.4.
Prototype: template T permutate(const T& a); template T permutate(const T& a); Description: Permute four elements in a vector. Template parameter n: each 2-bit field (from LSB) selects the content of one element location (from low address) in the destination operand. i.e., r[0] := a[n(1:0)] r[1] := a[n(3:2)] r[2] := a[n(5:4)] r[3] := a[n(7:6)] Template parameter a0 ~ a3: selects the contents of one element location in the destination operand. ie.
... r15 = (mask15 & 0x80) ? 0 : SELECT(a, mask15 & 0x0f) r0-r15 and mask0-mask15 are the sequentially ordered 8-bit components of return value r and parameter mask. r0 and mask0 are the least significant 8 bits. SELECT(a, n) extracts the nth 8-bit parameter from a. The 0th 8-bit parameter is the least significant 8-bits. mask provides the mapping of bytes from parameter a to bytes in the result. If the byte in mask has its highest bit set, the corresponding byte in the result will be set to zero. 9.4.
Description: Take for vector operands and perform horizontal addition to each vector. The return vector contains the result for each operand vector. Input: {A00, A01, A02, A03}, {A10, A11, A12, A13}, {A20, A21, A22, A23}, {A30, A31, A32, A33} Output: {R0, R1, R2, R3}, R0 = A00+A01+ A02+ A03 R1= A10+A11+A12+A13 R2= A20+A21+A22+A23 R3= A30+A31+A32+A33 9.4.
Description: Perform a saturated horizontal addition of all elements in the operand vector. Obsoleted. Please use saturated_hadd instead. 9.4.40 saturated_add Vector type: T = vb/s/ub/us/cb/cs/cub/cus Prototype: T saturated_add(const T& a, const T& b); Description: Element-wise saturated add 9.4.41 saturated_pack Vector type: T = vs/i/cs Prototype: T saturated_pack(const T& a, const T& b); Description: Saturated packs the 2 source vectors into one.
9.4.45 set_zero Vector type: T = vb/s/i/q/f/ub/us/ui/uq/cb/cs/ci/cq/cf/cub/cus/cui/cuq Prototype: void set_zero(T& a); Description: Clear all bits in a vector 9.4.46 shift_element_left Vector type: T = vs/i/q/cs/ci/cq/us/ui/uq/cus/cui/cuq Prototype: T shift_left(const T& a, int nbits); Description: Shift the whole vector left by specified elements 9.4.
Description: Element-wise polarization on the first operand based on the second operand, ie. r[n] := (b[n] < 0) ? -a[n] : ((b[n] == 0) ? 0 : a[n]) 9.4.51 smax Vector type: T = vs/cs/ub/cub/b/cb/us/cus Prototype: T smax(const T& a, const T& b); Description: Compute element-wise maximum 9.4.52 smin Vector type: T = vs/cs/ub/cub/b/cb/us/cus Prototype: T smin(const T& a, const T& b); Description: Compute element-wise minimum 9.4.
Prototype: T sub(const T & a, const T & b); Description: Element-wise Subtract 9.4.57 unpack Vector type: T = vb/s/i/ub/us/ui Vector type: T = vs/i/q/us/ui/uq Prototype: void unpack(TO& r1, TO& r2, const T& a); Description: Unpack elements in source vector to 2 destination vectors. Each element will be unpacked to a double-length field; r1 gets the unpacked elements in the lower half of the source vector, r2 get elements in the higher half. 9.4.
Prototype: template void rep::vshift_right (T * psrc, int nbits); Description: Shift consequent N elements in psrc buffer to the right by “nbits” bits, and store to original buffer separately. 9.4.62 rep:: vsqrnorm Prototype: template void rep::vsqrnorm (vi * pdst, vi * psrc); Description: Compute the squared norm of consequent N elements in psrc buffer, and store to pdst buffer separately. 9.4.
Chapter 10. The Sample SoftWiFi Driver Since version 1.1, Sora SDK package includes the SoftWiFi sample SDR driver. SoftWiFi implements the IEEE 802.11a/b/g standards. The driver follows the Windows NDIS 5 framework and exposes a virtual Ethernet interface to the operating system. All applications can run on SoftWiFi without modification. The SoftWiFi driver can be found in folder %SORA_ROOT%\src\driver.
receiving queue. Another thread monitors this receiving queue, and indicates the correctly received frames to NDIS. The initialization routines of the link layer, MAC and PHY are in sdr_ll_main.c, sdr_mac_main.c, and sdr_phy_main.c. NDIS Wrapper Sample SDR driver Sample Link Layer Recv thrd Send thrd PHY Tx Send Frame Queue Complete Queue FSM thrd Recv Frame Queue Frame Indication/ Completion MAC FSM Tx Queue Decoder thrd PHY Rx ACK Cache Rx Stream RCB (HW) Figure 37.
-c | --channel [channel NO.] -f | --freqoffset [Hz] Channel 1:2412MHz, 2:2417MHz, 3:2422MHz ..., 15: 2482MHz, 36:5180MHz, 40:5200MHz ... Set frequency offset, can be negative. Real central frequency is channel frequency plus this frequency offset value. -a | --setmacaddr Set MAC address for SDR miniport driver. -p | --preamble [0/1] -s | --spdmax [blocks] -t | --spdthd [energy] 0/1 for long/short preamble for 11b set 802.11b power detection block timeout set energy threshold for 802.
very handy to use demode11 to read from a dump file to debug or test your modifications to baseband algorithms. The usage of the demod11 tool is summarized below. -a | --802.11a -b | --802.11b specify 802.11a mode specify 802.
Chapter 11. Tools and Utilities 11.1 dut tool 11.1.1 Using dut to configure the HwTest driver dut is the configuration tool for the HwTest driver. The command dut start will enable the driver as well as the UMX library. You can use dut to configure radio parameters. For example, run dut txgain --value 0x1000 to set the transmission gain. Or, you can set the receiving gain with dut rxgain --value 0x1000. Or you can set the central frequency of the radio with dut centralfreq --value 2414.
dut txdone --sid 0x01. 11.1.3 Dut usage summary start stop Enable the radio hardware. Disable the radio hardware. tx Transmit a signal txdone Remove a stored signal from the RCB memory dump Dump the radio Rx channel txgain Set Tx Gain rxgain Set Rx Gain rxpa info Set RX PA.
You can press “o” to open a dump file and start/stop the processing with the space key. You can also set a “processing point” by clicking on the overview panel. Sdscope-11a also allows you to specify the sampling rate of the dump file with command line, sdscope-11a –s[40|44]. Key Function o/O Open a dump file Space Start or Pause the processing s/S Rotate the sampling rate (sdscope-11a only) Left Arrow/Right Arrow Speedup or Slow down Up Arrow/Down Arrow Scale up/down of amplitude 11.
Figure 38. The main window of SrView.
Constellation view of raw I/Q samples Amplitude of raw I/Q samples Amplitude of Constellation of decimated decimated I/Q samples I/Q samples Constellation view after barker despreading Amplitude after barker despreading Overview of the whole waveform Demapper results Descramble results Frame content Frame header information Figure 39. The main window of sdscope-11b.
Constellation view of raw I/Q samples Energy and autocorrelation view Symbol view Information panel Channel view Constellation of symbols Overview panel Constellation view of raw I/Q samples Decoded bytes CRC Energy and autocorrelation view Symbol view Information panel Channel view Constellation of symbols Overview panel Decoded bytes CRC Figure 40. The main window of sdscope-11a.
11.4 Hardware Verification Tool The Hardware Verification Tool (HVT) is a helpful tool to test and configure Sora hardware components. HVT supports two types of tests: the sine test (single tone test) and the SNR test (wide-band test). To use HVT, you need two Sora boxes: one works as sender and the other is a receiver. In the sine test, the sender transmits a 1MHz sine signal; the receiver captures and analyzes the received signal.
Table 2 (at page 18). HVT is based on UMX APIs. Please make sure the RCB driver and the HwTest driver are properly installed. 11.4.1 The Sine Wave Test a) Start the test. Set up two Sora boxes. Place the two antennas about one meter apart. Select sine test on both boxes. Choose one box as the sender (select send) and the other as the receiver (select receive). Click start button (b) at the sender. You will see the sender’s status bar (j) showing “Sending 1MHz sine wave”.
[Calibration] freqOffsetLineSlope=-0.894473 freqOffsetLineIntercept=121178 Figure 41. A sample configuration file after calibration. b) Diagnosis The user can use the sine test to pin-point several hardware related issues. Table 7 summarizes some typical graphs and their explanations. This table can be displayed anytime when the user clicks the suggestion button (d) at the receiver. Table 7. Typical graphs shown in the sine test and their descriptions. Overview Constellation Description Normal signal.
Saturated signal. The received signal has been saturated. Please try the following actions: 1. Decrease the rxpa and rxgain or enable AGC at the receiver; 2. Decrease the txgain at the sender side; 3. Move the antennas further away. 11.4.2 The SNR Test a) Start a test Set up two Sora boxes. Place the two antennas about one meter apart. Select snr test on both boxes. Choose one box as the sender (select send) and the other as the receiver (select receive).
Table 8. Typical graphs shown in the SNR test and their descriptions. Overview Constellation Description Channel quality is high. The 16QAM constellation graph is clearly displayed. No signal. The receiver receives no signal. Please try the following actions to solve this problem: 1. Check if the hardware are connected properly; 2. Check if the drivers are installed properly; 3. Move the antennas closer; 4. Increase txgain at the sender side; 5.
No frame detected. The receiver receives signals but no valid frame is detected. Please try the following actions to solve this problem: 1. Make sure no other interfering sources exist; 2. Increase txgain at the sender side; 3. Increase rxpa and rxgain or enable AGC at the receiver side; 4. Move the antennas closer; 5. Adjust frequency offset. You can find proper values using the sine test; 6. Reset hardware and disable/enable the drivers. 11.4.
11.5 DbgPlot DbgPlot is a versatile tools that allows programs to dynamic generate graphics in real-time. It is a powerful tool for real-time monitoring and debugging DSP programs. Please refer to the separated debug plot manual for complete information (http://research.microsoft.com/apps/pubs/?id=160801).
Chapter 12. Reference 12.1 Kernel Mode API 1) SoraAllocateRadioFromRCBDevice HRESULT SoraAllocateRadioFromRCBDevice( IN OUT PLIST_ENTRY pRadiosHead, IN ULONG nRadio, IN PCWSTR UserName ); Parameters pRadiosHead Pointer to a list head the returned radio objects are linked to. nRadio Number of the radios to allocate. UserName Pointer to a Unicode string specifying a tag for the allocated radios. Each allocation code path should use an identical tag to help system to identify the code path.
The allocated radios should be released using SoraReleaseRadios. Requirements IRQL: PASSIVE_LEVEL Headers: Include sora.h See Also SoraReleaseRadios, SoraRadioInitialize, SoraStartRadio. 2) SoraReleaseRadios VOID SoraReleaseRadios( IN LIST_ENTRY *pRadiosHead ); Parameters pRadiosHead Pointer to the radio list. Return Value None Comments SoraReleaseRadios releases radio objects allocated by SoraAllocateRadioFromRCBDevice. Requirements IRQL: PASSIVE_LEVEL Headers: Include sora.
Pointer to a radio object. pReserved Reserved. nTxSampleBufSize The size of the buffer that holds the transmission digital samples. Each radio object is assigned to a unique Tx sample buffer. nRxSampleBufSize The size of the buffer that holds the received digital samples. The RCB will fill the Rx sample buffer with latest received samples. The size must be a multiple of 4K. Return Value SoraRadioInitialize returns E_NOT_ENOUGH_CONTINUOUS_PHY_MEM if not enough memory is available.
pRadio Pointer to the radio object to be enabled. RxGain Reception gain in units of 1/256 dB, e.g. a value of 0x200 means 2dB. TxGain Transmission gain in units of 1/256 dB, e.g. a value of 0x200 means 2dB. pConfig Pointer to a reserved configuration structure. Return Value SoraRadioStart returns S_OK if the radio hardware is enabled successfully. It returns E_RADIO_NOT_CONFIGURED if the radio object is not properly initialized and E_REG_WRITE_FAIL if hardware fails.
Parameters pRadio Pointer to a radio object. Return Value SoraRadioGetRxStream returns the pointer of RX_STREAM associated with the radio object. Comments When a radio object is initialized, an RX_STREAM object is also created and associated to the radio object. A SDR driver should use the RX_STREAM object to read the radio’s Rx sample buffer. Requirements IRQL: <= DISPATCH_LEVEL Headers: Include Sora.
The return value is S_OK if a signal block is succeeded read. Otherwise, the return value is E_FETCH_SIGNAL_HW_TIMEOUT if no new signal blocks are available in a timeout period. This may indicate an error in hardware. Comments This function gets a new signal block from the RX_STREAM object. pbTouched points to a flag variable that receives the indication whether or not the returned signal block is the last one in the RX channel. If the flag is set, the RX channel of the radio is empty.
SoraRadioReadRxStream 8) SoraInitSignalCache HRESULT SoraInitSignalCache( OUT PSIGNAL_CACHE IN PSORA_RADIO IN ULONG IN ULONG ); pCache, pRadio, uSize, uMaxEntryNum Parameters pCache Pointer to a signal cache object to be initalized. pRadio Pointer to the radio object that allocates the signal cache. uSize The size, in bytes, of each entry in the signal cache. The size must be a multiple of 128byte. uMaxEntryNum The maximum number of entries in the signal cache.
See Also SoraCleanSignalCache, SoraGetSignal, SoraInsertSignal. 9) SoraInsertSignal HRESULT SoraInsertSignal( IN PSIGNAL_CACHE IN PCOMPLEX8 IN PHYSICAL_ADDRESS IN ULONG IN CACHE_KEY ); pCache, pSampleBuffer, *pSampleBufferPa, uSampleSize, Key Parameters pCache Pointer to the signal cache object. pSampleBuffer Pointer to a buffer containing the signal samples to be inserted. pSampleBufferPa Pointer to the physical address structure of the sample buffer.
Requirements IRQL : <= DPC_LEVEL Headers: sora.h See Also SoraGetSignal, SORA_HW_FAST_TX. 10) SoraGetSignal PTX_DESC SORAAPI SoraGetSignal ( IN PSIGNAL_CACHE pCache, IN CACHE_KEY Key ); Parameters pCache Pointer to the signal cache object from which to retrieve a signal. Key The 8-byte key associated to a cache entry. Return Value SoraGetSignal returns a TX descriptor of the stored signal; otherwise, it returns NULL if the key cannot be found in the cache.
Return Value None. Comments The SDR application should call SoraCleanSignalCache to free the RCB onboard memory. 12) SoraHwSetSampleClock VOID SoraHwSetSampleClock ( PSORA_RADIO pRadio, ULONG Hz ); Parameters pRadio Pointer to the radio object to be configured. Hz The desired sampling rate, in unit of Hz. Return Value None. Comments The sampling clock depends on the implementation of the RF front-end board.
HzFine The fine part (Hz) of the desired central frequency. Return Value None. Comments SoraHwSetCentralFreq sets the central frequency of the RF front-end. The desired central frequency is split into the coarse part (kHz) and the fine part (Hz), and Central freq = kHzCoarse * 1000 + HzFine. 14) SoraHwSetFreqCompensation VOID SoraHwSetFreqCompensation ( PSORA_RADIO pRadio, LONG lFreq ); Parameters pRadio Pointer to the radio object to be configured. lFreq The frequency, in Hz, to be compensated.
SoraHwSetTXVGA1 ( PSORA_RADIO pRadio, ULONG uGain ); Parameters pRadio Pointer to the radio object to be configured. uGain The value, in unit of 1/256 dB, to be set to transmission Variable Gain Amplifier (VGA) of the RF front-end. Return Value None Comments SoraHwSetTXVGA1 sets the transmission variable gain amplifier of the RF front-end. The gain control is specified in unit of 1/256 dB. However, the true precision of VGA depends on the implementation of the RF front-end.
SoraHwSetRXPA writes a value to the virtual control register of the RF front-end to provide a hint to configure LNA on the reception path. The value depends on the implementation of the RF front-end board. For USRP XCVR2450 board, there can be three effective configurations: 0 (or 0x1000) means 0dB, 0x2000 means 16dB, and 0x3000 means 32dB. SoraHwSetRXVGA1 VOID SoraHwSetRXVGA1( PSORA_RADIO pRadio, ULONG uGain ); Parameters pRadio Pointer to the radio object to be configured.
Return Value SORA_HW_TX_TRANSFER returns S_OK on success. Comments SORA_HW_TX_TRANSFER downloads the modulated signals of a frame from the shared TX sample buffer to the memory location on RCB as indicated in the packet base object. 18) SORA_HW _TX HRESULT SORA_HW _TX ( PSORA_RADIO pRadio, PPACKET_BASE pPacket ); Parameters pRadio Pointer to the radio object to send the signal. pPacket Pointer to the packet base object. Return Value SORA_HW _TX returns S_OK on success.
pTxDesc Pointer to the TX descriptor. Return Value SORA_HW_FAST_TX returns S_OK on success. Comments SORA_HW_FAST_TX indicates the hardware to send out the signal at the memory location on the RCB as indicated in the Tx Descriptor. A Tx Descriptor is normally obtained after querying an entry of a signal cache. 20) SORA_HW_ENABLE_RX VOID SORA_HW_ENABLE_RX ( PSORA_RADIO pRadio ); Parameters pRadio Pointer to the radio object whose RX channel is to be enabled. Return Value None.
Comments SORA_HW_STOP_RX disables the RX channel of a radio object. Once the RX channel is disabled, the DMA operations are stopped. 22) SoraPacketGetTxSampleBuffer VOID SORAAPI SoraPacketGetTxSampleBuffer( IN PPACKET_BASE pPacket, OUT PTXSAMPLE *ppBuf, OUT PULONG pBufSize ); Parameters pPacket Pointer to the packet base object. ppBuf Pointer to a sample buffer pointer. pBufSize Pointer to an unsigned variable that receives the sample buffer size. Return Value None.
Return Value None. Comments SoraPacketSetSignalLength specifies the actual bytes that have been occupied by the modulated signal of a data frame. The SDR driver should call this function right after it stores the modulated waveform in the TX sample buffer. 24) SoraPacketSetTXDone __inline void SoraPacketSetTXDone ( IN OUT PPACKET_BASE pPacket ); Parameters pPacket Pointer to the packet base object. Return Value None. Comments SoraPacketSetTXDone sets the status of a packet base object to PACKET_TX_DONE.
SoraThreadAlloc allocates a Sora exclusive thread object. A Sora exclusive thread cannot be preempted by any other thread and should be only used for real-time tasks on a multi-core system. After allocation, the SDR application should call SoraThreadStart to start an exclusive thread. Requirements IRQL: <= DISPATCH_LEVEL Headers: Include thread_if.h See Also SoraThreadFree 26) SoraThreadFree VOID SoraThreadFree ( IN HANDLE hThread ); Parameters hThread Handle to the Sora thread object. Return Value None.
IN HANDLE hThread, IN PSORA_UTHREAD_PROC pUserRoutine, IN PVOID pParameter ); Parameters hThread Handle to the Sora thread object. pUserRoutine Address of a routine that the Sora thread calls periodically. pParameter Parameter provided to the user routine. Return Value SoraThreadStart returns TRUE if success; otherwise it returns FALSE. Comments SoraThreadStart starts a Sora exclusive thread that will call the user specified routine periodically.
Headers: Include thread_if.h See Also SoraThreadStop 28) SoraThreadStop VOID SoraThreadStop( IN HANDLE hThread ); Parameters hThread Handle of the Sora thread object. Return Value None. Comments SoraThreadStop stops the running Sora thread. Caution: Never call SoraThreadStop to terminate a Sora thread from its user routine. It will cause a dead-lock. Requirements IRQL: PASSIVE_LEVEL Headers: Include thread_if.h See Also SoraThreadStart 12.
BOOLEAN SoraUInitUserExtension ( const char * szDevName ); Parameters szDevName Pointer to the name of device supporting UMX API. Return Value SoraUInitUserExtension returns true if the initialization succeeds; otherwise, it returns false. Comments SoraUInitUserExtension initializes the user-mode extension. The device name should be “\\.\HWTest”. 30) SoraUCleanUserExtension VOID SoraUCleanUserExtension (); Parameters None. Return Value None.
Return Value SoraURadioStart returns S_OK if the radio hardware is enabled successfully. Comments SoraURadioStart enables the RF front-end and initializes the gain control parameters. 32) SoraURadioSetSampleRate HRESULT SoraURadioSetSampleRate( IN ULONG uRadioID, IN ULONG MHz ); Parameters uRadioID The ID referring to the radio object. MHz The desired sampling rate, in unit of MHz. Return Value SoraURadioSetSampleRate returns S_OK if the sample rate is successfully set.
SoraURadioSetCentralFreq returns S_OK if the central frequency is successfully set. Comments SoraURadioSetCentralFreq sets the central frequency of the RF front-end. 34) SoraURadioSetFreqOffset HRESULT SoraURadioSetFreqOffset( ULONG uRadioID, LONG lFreq ); Parameters uRadioID The ID referring to the radio object. lFreq The frequency offset, in Hz, to be set. Return Value SoraURadioSetFreqOffset returns S_OK if the frequency offset is successfully set.
uGain The value, in unit of 1/256 dB, to be set to transmission Variable Gain Amplifier (VGA) of the RF front-end. Return Value SoraURadioSetTxGain returns S_OK if the Tx Gain is successfully set. Comments SoraURadioSetTxGain sets the transmission variable gain amplifier of the RF front-end. The gain control is specified in unit of 1/256 dB. However, the true precision of VGA depends on the implementation of the RF front-end.
effective configurations: 0 (or 0x1000) means 0dB, 0x2000 means 16dB, and 0x3000 means 32dB. 37) SoraURadioSetRxGain HRESULT SoraURadioSetRxGain ( ULONG uRadioID, ULONG uGain ); Parameters uRadioID The ID referring to the radio object. uGain The value, in unit of 1/256 dB, to be set to the reception Variable Gain Amplifier (VGA) of the RF front-end. Return Value SoraURadioSetRxGain returns S_OK if the Rx Gain is successfully set.
puSize Address of an unsigned long variable that receives the size of the mapped TX sample buffer. Return Value SoraURadioMapTxSampleBuf returns S_OK if success. Comments SoraURadioMapTxSampleBuf maps the TX sample buffer of the radio object into the usermode space. The radio object is specified by RadioID. The function needs to be called only once during the initialization phase of a SDR application.
40) SoraURadioTx HRESULT SoraURadioTx ( IN ULONG uRadioID, IN ULONG TxID ); Parameters uRadioID The ID referring to the radio object. TxID TX ID of a signal to be transmitted. Return Value SoraURadioTx returns S_OK if success. Comments SoraURadioTx instructs the hardware to send out the signal indicated by the TX ID. The signal should have been transferred to the RCB memory using SoraURadioTransfer.
42) SoraURadioUnmapTxSampleBuf HRESULT SoraURadioUnmapTxSampleBuf ( IN ULONG uRadioID, IN PVOID pMappedBuf ); Parameters uRadioID The ID referring to the radio object. pMappedBuf Pointer to the mapped TX sample buffer. Return Value SoraURadioUnmapTxSampleBuf returns S_OK if success. Comments SoraURadioUnmapTxSampleBuf releases the mapped TX sample buffer. The user-mode address, as pointed by pMappedBuf, is no longer valid.
Return Value SoraURadioMapRxSampleBuf returns S_OK if success. Comments SoraURadioMapRxSampleBuf maps the RX sample buffer of the radio object into the usermode space. The radio object is specified by uRadioID. SoraURadioMapRxSampleBuf needs to be called only once during the initialization phase of a SDR application. The SDR application then can directly read digital samples from the RX sample buffer via this mapped address.
pRxStream Pointer to a RX_STREAM object. uRadioID The ID referring to the radio object. pMappedRxBuf Pointer to the mapped RX sample buffer. uSize Size, in bytes, of the mapped RX sample buffer. Return Value SoraURadioAllocRxStream returns S_OK if success. It returns E_RADIO_NOT_CONFIGURED if the radio object is not properly initialized. It returns E_FAIL if the radio object cannot allocate a new RX_STREAM object.
Return Value The return value is S_OK if a signal block is succeeded read. Otherwise, the return value is E_FETCH_SIGNAL_HW_TIMEOUT if no new signal blocks are available in a timeout period. This may indicate an error in hardware. Comments This function gets a new signal block from the RX_STREAM object. pbTouched points to a flag variable that receives the indication whether or not the returned signal block is the last one in the RX channel. If the flag is set, the RX channel of the radio is empty.
48) SoraURadioReleaseRxStream VOID SORAAPI SoraURadioReleaseRxStream ( IN PSORA_RADIO_RX_STREAM pRxStream, IN ULONG uRadioID, ); Parameters pRxStream Pointer to a RX_STREAM object. uRadioID The ID referring to the radio object. Return Value None. Comments SoraURadioReleaseRxStream releases the RX_STREAM object that allocated from SoraURadioAllocRxStream. Once SoraURadioReleaseRxStream is called, the RX_STREAM is not valid anymore.
50) SoraUReleaseTxBufLock. VOID SoraUReleaseTxBufLock ( ULONG uRadioID ); Parameters uRadioID ID of the radio object whose TX buffer lock is to be released. Return Value None. Comments SoraUReleaseTxBufLock releases the shared TX buffer lock of the radio object. The SDR application should previously obtain the TX buffer lock by SoraUAcquireTxBufLock.
52) SoraUReadRadioRegister HRESULT SoraUReadRadioRegister ( IN ULONG uRadioID, IN ULONG uAddr, IN ULONG * puVal ); Parameters uRadioID ID of the radio object to be configured. uAddr Address of the register on the RF front-end board. uValue Address of an unsigned long variable that receives the register value. Return Value SoraUReadRadioRegister returns S_OK if success. Comments SoraUReadRadioRegister reads the value in a virtual register on the RF front-end board.
SoraUIndicateRxPacket returns S_OK if success. Comments SoraUIndicateRxPacket indicates a demodulated packet to the HwTest driver, which then indicates the packet to the upper layers, i.e. TCP/IP, for further processing. SoraUIndicateRxPacket enables the seamless integration of the SDR application with Windows network stack. 54) SoraUThreadAlloc HANDLE SoraUThreadAlloc (); Parameters None Return Value SoraUThreadAlloc returns NULL if an error occurred; otherwise it returns the handle of a Sora thread.
None. Comments SoraUThreadFree release the Sora thread object that is previously allocated by SoraUThreadAlloc. 56) SoraUThreadStart BOOLEAN SoraUThreadStart ( IN HANDLE hThread, IN PSORA_UTHREAD_PROC pUserRoutine, IN PVOID pParameter ); Parameters hThread Handle to the Sora thread object. pUserRoutine Address of a routine that the Sora thread calls periodically. pParameter Parameter provided to the user routine. Return Value SoraUThreadStart returns TRUE if success; otherwise it returns FALSE.
57) SoraUThreadStop VOID SoraUThreadStop( IN HANDLE hThread ); Parameters hThread Handle of the Sora thread object. Return Value None. Comments SoraUThreadStop stops the running Sora thread. Caution: Never call SoraUThreadStop to terminate a Sora thread from its user routine. It will cause a dead-lock.
SoraUDisableGetTxPacket is called to disable the SDR application to obtain a data packet from hwtest driver. SoraUGetTxPacket returns ERROR_INVALID_HANDLE if the UMX is not initialized. SoraUGetTxPacket returns ERROR_TIMEOUT if the timeout interval has elapsed without getting a data packet. Comments SoraUGetTxPacket allows the SDR application to retrieve an Ethernet packet from the HWTest driver, which has received these data packets from upper layers, e.g. TCP/IP, in the Windows network stack.
Parameters None Return Value SoraUEnableGetTxPacket returns S_OK if success. Comments SoraUEnableGetTxPacket should be called before calling SoraUGetTxPacket. 61) SoraUDisableGetTxPacket HRESULT SoraUDisableGetTxPacket (); Parameters None Return Value SoraUDisableGetTxPacket returns S_OK if the function succeeds. Comments SoraUDisableGetTxPacket releases all blocking calls to SoraUGetTxPacket and disables its function. Subsequent calls to SoraUGetTxPacket will return ERROR_CANCELLED.
SoraUAllocBuffer allocates the required kernel buffer and is usually used for modulation. User is able to store the modulated signal in the address returned by SoraUAllocBuffer and invoke SoraURadioTransferEx subsequently to transfer it. Kernel buffer is a limited rare resource. Once the buffer is obtained, hold and reuse it unless you don’t need it anymore. Frequent allocation and release is not recommended and might fail.
SampleSize The signal length stored in SampleBuffer. pTxID Address of an ULONG variable that receives the TxID of transferred signal. Return Value SoraURadioTransfer returns S_OK if success. Comments SoraURadioTransferEx allocates a block of RCB memory and transfers the modulated signal to that memory block. The returned TxID can be later used in SoraURadioTx to transfer the signal or used in SoraURadioTxFree to remove the signal from RCB memory.
Determine whether current CPU support Time Stamp Counter (TSC) instructions 66) SoraSetTimestampMethod int SoraSetTimestampMethod (PTIMESTAMPINFO pInfo, int use_tsc ); Parameters pInfo pointer to the TIMESTAMPINFO object use_tsc true means use TSC, false means not Return value original method of TIMESTAMPINFO object Comments Set the method of TIMESTAMPINFO object to specified method 67) InitializeTimestampInfo void InitializeTimestampInfo ( PTIMESTAMPINFO pInfo, bool use_tsc = true ); Parameters pInfo poi
Intialize TIMESTAMPINFO object 68) SoraGetCPUTimestamp ULONGLONG SoraGetCPUTimestamp (PTIMESTAMPINFO pTSInfo); Parameters pTSInfo pointer to the TIMESTAMPINFO object Return value current timestamp Comments Get current timestamp by the method specified by TIMESTAMPINFO object 69) SoraGetTimeofDay ULONGLONG SoraGetTimeofDay (PTIMESTAMPINFO pTSInfo); Parameters pTSInfo pointer to the TIMESTAMPINFO object Return value the number of us has passed since last reboot Comments Get the number of us has passed since
us the microseond value Return value true Comments Parse the microseond value into hh:mm:ss.us format stored in SORATIMEOFDAYINFO object 71) SoraTimeElapsed ULONGLONG SoraTimeElapsed ( ULONGLONG ts, PTIMESTAMPINFO tsinfo ) Parameters info pointer to the SORATIMEOFDAYINFO object us the microseonds value Return value nanoseconds value Comments Convert ticks value to nanoseconds.
the nanoseconds value Return value none Comments Spinlock specified nanoseconds 141
