doc/manuals/chapters/remsim-bankd.adoc

== remsim-bankd

The `remsim-bankd` (SIM Bank Daemon) manages one given SIM bank.  The
initial implementation supports a PC/SC driver to expose any PC/SC
compatible card readers as SIM bank.

`remsim-bankd` initially connects via a RSPRO control connection to
`remsim-server` at startup, and will in turn receive a set of initial
[client,slot]:[bankd,slot] mappings.  These mappings determine which
slot on the client (corresponding to a modem) is mapped to which slot on
the SIM bank.  Mappings can be updated by `remsim-server` at any given
point in time.

`remsim-bankd` implements a RSPRO server, where it listens to connections
from `remsim-clients`.

As PC/SC only offers a blocking API, there is one thread per PC/SC slot.
This thread will perform blocking I/O on the socket towards the client,
and blocking API calls on PC/SC.

In terms of thread handling, we do:

* accept() handling in [spare] worker threads
** this means blocking I/O can be used, as each worker thread only has
   one TCP connection
** client identifies itself with client:slot
** lookup mapping based on client:slot (using mutex for protection)
** open the reader based on the lookup result

The worker threads initially don't have any mapping to a specific
reader, and that mapping is only established at a later point after the
client has identified itself.  The advantage is that the entire bankd
can live without any non-blocking I/O.

The main thread handles the connection to `remsim-server`, where it can
also use non-blocking I/O.  However, re-connection would be required, to
avoid stalling all banks/cards in the event of a connection loss to the
server.

worker threads have the following states:
* INIT (just started)
* ACCEPTING (they're blocking in the accept() call on the server socket fd)
* CONNECTED_WAIT_ID (TCP established, but peer not yet identified itself)
* CONNECTED_CLIENT (TCP established, client has identified itself, no mapping)
* CONNECTED_CLIENT_MAPPED (TCP established, client has identified itself, mapping exists)
* CONNECTED_CLIENT_MAPPED_CARD (TCP established, client identified, mapping exists, card opened)
* CONNECTED_SERVER (TCP established, server has identified itself)

Once the client disconnects, or any other error occurs (such as card I/O
errors), the worker thread either returns to INIT state (closing client
socket and reader), or it terminates.  Termination would mean that the
main thread would have to do non-blocking join to detect client
termination and then re-spawn clients, so the "return to INIT state"
approach seems to make more sense.


=== Running

`remsim-bankd` currently has the following command-line options:

==== SYNOPSIS

*remsim-bankd* [-h] [-i A.B.C.D] [-p <1-65535>] [-b <1-65535>] [-I A.B.C.D] [-P <1-65535> ]

==== OPTIONS

*-h, --help*::
  Print a short help message about the supported options
*-i, --server-host A.B.C.D*::
  Specify the remote IP address/hostname of the remsim-server to which this bankd
  shall establish its <<RSPRO>> control connection
*-p, --server-port <1-65535>*::
  Specify the remote TCP port number of the remsim-server to whihc this bankd
  shall establish its <<RSPRO>> control connection
*-b, --bank-id <1-65535>*::
  Specify the numeric bank identifier of the SIM bank this bankd instance
  operates.  Must be unique among all banks connecting to the same remsim-server.
*-I, --bind-IP A.B.C.D*::
  Specify the local IP address to which the socket for incoming connections
  from remsim-clients is bound to.
*-P, --bind-port <1-65535>*::
  Specify the local TCP port to whicc the socket for incoming connections
  from remsim-clients is bound to.

=== Logging

remsim-bankd currently logs to stdout only, and the logging verbosity
is not yet configurable.  However, as the libosmocore logging framework
is used, extending this is an easy modification.

=== `bankd_pcsc_slots.csv` CSV file

bankd expects a CSV file `bankd_pcsc_slots.csv` in the current working directory at startup.

This CSV file specifies the mapping between the string names of the PCSC
readers and the <<RSPRO>> bandk/slot numbers.  The format is as follows:

.Example: CSV file mapping bankd slots 0..4 to an ACS ACR33U-A1 reader slots
----
"1","0","ACS ACR33 ICC Reader 00 00"
"1","1","ACS ACR33 ICC Reader 00 01"
"1","2","ACS ACR33 ICC Reader 00 02"
"1","3","ACS ACR33 ICC Reader 00 03"
"1","4","ACS ACR33 ICC Reader 00 04"
----