-------------------------------------------------------------------------------
Build.

Make sure you've built with debug info:

  cd ~/openairinterface5g # or wherever
  source oaienv
  cd cmake_targets
  ./build_oai --UE --eNB --verbose-compile --run-with-gdb RelWithDebInfo
  make -C ran_build/build -j4 lte-softmodem lte-uesoftmodem

-------------------------------------------------------------------------------
Verify.

Verify the build was done correctly:

$ ./gdb-helper
...
Reading symbols from ./ran_build/build/lte-softmodem...done.
(gdb) b main
Breakpoint 1 at 0x59f110: file /local/episys/openairinterface5g/targets/RT/USER/lte-softmodem.c, line 516.
(gdb) run
Starting program: /local/episys/openairinterface5g/cmake_targets/ran_build/build/lte-softmodem -O ../ci-scripts/conf_files/rcc.band7.tm1.nfapi.conf --noS1
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".

Breakpoint 1, main (argc=4, argv=0x7fffffffe058) at /local/episys/openairinterface5g/targets/RT/USER/lte-softmodem.c:516
516     {
(gdb) list
511       pthread_mutex_unlock(&nfapi_sync_mutex);
512       printf( "NFAPI: got sync (%s)\n", thread_name);
513     }
514
515     int main ( int argc, char **argv )
516     {
517       struct sched_param param =
518       {
519         .sched_priority = 79
520       };
(gdb) n
521       if (sched_setscheduler( 0, SCHED_RR, &param ) == -1 )
(gdb) quit
A debugging session is active.

        Inferior 1 [process 19964] will be killed.

Quit anyway? (y or n) y
$

If gdb says "no debugging symbols found" then clean your workspace and re-do
the build as above.

(gdb) b main

-------------------------------------------------------------------------------
Password-less sudo.

Vscode launches lte-softmodem via sudo.  Make sure sudo does not prompt you
for a password:

  sudo -n id

If that command fails, do the following:

  echo "$USER ALL=(ALL) NOPASSWD: ALL" | sudo tee -a /etc/sudoers

Then verify:

  sudo -n id

-------------------------------------------------------------------------------
Vscode.

Launch Vscode:

  cd ~/openairinterface5g # or wherever
  code . targets/RT/USER/lte-softmodem.c .vscode/launch.json

See launch.json for details about how vscode launches lte-softmodem for debugging.

For example, in lte-softmodem.c, scroll to main() and click the line number to
the left of main to add a breakpoint.  then do Run => Start debugging (F5) to
run lte-softmodem in the debugger

-------------------------------------------------------------------------------
Running Vscode remotely.

Currently, running Vscode remotely (via an X-Windows connection) does not work
-- the Vscode window appears but remains blank.  Presumably the Vscode
developers will fix this problem eventually.  Meanwhile, you can use `sshfs`
to make the remote filesystem appear locally and then run Vscode locally.

On the local machine:

  $ remote=surfer      # or whatever the remote machine's name is
  $ mkdir ~/openairinterface5g
  $ sshfs $remote:openairinterface5g ~/openairinterface5g
  $ ls ~/openairinterface5g
   CHANGELOG.md    CONTRIBUTING.md   nfapi       openair3            targets
  ...
  $ code ~/openairinterface5g
  $

The remote and local pathnames of your openairinterface5g workspace should be
the same.  If they're different, use a symlink on the local machine to make
the remote pathnames work locally.  This part is important because executables
built on $remote contain references to the source files and vscode & gdb will
use those pathnames to find the source files.

You may want to locally mount the remote logs directory, too:

  $ mkdir ~/logs
  $ sshfs $remote:logs ~/logs
  $ ls -l ~/logs
  total 40
  lrwxrwxrwx 1 1002 1002   22 Jan 17 11:54 latest -> logs-2021-01-17-085419
  drwxr-xr-x 1 1002 1002 4096 Jan 17 11:54 logs-2021-01-17-085419
  $

That will give you access to core files collected by lte_testscript.py, for
example.

  $ file ~/logs/latest/0001/coredump-6699
  /home/michael/logs/latest/0001/coredump-6699: ELF 64-bit LSB core file,
  x86-64, version 1 (SYSV), SVR4-style, from './ran_build/build/lte-softmodem
  -O ../ci-scripts/conf_files/rcc.band7.tm1.nfapi', real uid: 0, effective
  uid: 0, real gid: 0, effective gid: 0, execfn:
  './ran_build/build/lte-softmodem', platform: 'x86_64'
  $
  $ file ~/openairinterface5g/cmake_targets/ran_build/build/lte-softmodem
  /home/michael/openairinterface5g/cmake_targets/ran_build/build/lte-softmodem:
  ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked,
  interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 2.6.32,
  BuildID[sha1]=831400d4aae5d43b94ef3b22ebbd635107de48ae, with debug_info, not
  stripped
  $

Verify gdb can access these remote files:

  $ gdb ~/openairinterface5g/cmake_targets/ran_build/build/lte-softmodem \
  ~/logs/latest/0001/coredump-6699
  ...
  Program terminated with signal SIGABRT, Aborted.
  #0  0x00007f7fd7d11438 in ?? ()
  [Current thread is 1 (LWP 39)]
  (gdb)

If this step is too slow, you may want to copy the executable and coredump
files to the local machine first.

  $ scp -C $remote:openairinterface5g/cmake_targets/ran_build/build/lte-softmodem .
  $ scp -C $remote:logs/latest/0001/coredump-6699 .
  $ gdb lte-softmodem coredump-6699

Note, the local and remote machines should be the same version of Linux (e.g.,
both Ubuntu 16.04).  Otherwise, gdb will likely have trouble understanding the
coredump.

To load the coredump into Vscode, modify launch.json to add "coreDumpPath".
You may also need to modify the "program" path and delete "miDebuggerPath".

--- .vscode/launch.json
+++ .vscode/launch.json
@@ -9,7 +9,7 @@
             "name": "(gdb) Launch",
             "type": "cppdbg",
             "request": "launch",
-            "program": "${workspaceFolder}/cmake_targets/ran_build/build/lte-so
+            "program": "/home/michael/tmp/lte-softmodem",
             "args": [
                 "-O", "../ci-scripts/conf_files/rcc.band7.tm1.nfapi.conf",
                 "--noS1"
@@ -19,14 +19,14 @@
             "environment": [],
             "externalConsole": false,
             "MIMode": "gdb",
-            "miDebuggerPath": "${workspaceFolder}/cmake_targets/sudo-gdb",
             "setupCommands": [
                 {
                     "description": "Enable pretty-printing for gdb",
                     "text": "-enable-pretty-printing",
                     "ignoreFailures": true
                 }
-            ]
+            ],
+            "coreDumpPath": "/home/michael/tmp/coredump-6699"
         }
     ]
 }

Then, in Vscode click the debug icon on the left navigation bar, then click
the green "play" triangle near the upper left corner of the window.  See the
"CALL STACK" near the lower left of the window.

-------------------------------------------------------------------------------
