--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/SIM-manipulation	Mon Mar 22 00:24:34 2021 +0000
@@ -0,0 +1,119 @@
+Using fc-simint and fc-simtool to manipulate SIM cards inside Calypso devices
+=============================================================================
+
+Starting with fc-host-tools-r15, our FreeCalypso host tools package includes a
+new utility called fc-simint that works together with fc-simtool and other SIM
+card manipulation tools maintained in the separate FC SIM tools package.
+
+fc-simint is not a standalone program - instead it is a front end to the
+hardware-agnostic fc-simtool main program.  Therefore, fc-simint cannot be used
+unless you install FC SIM tools (fc-simtool and its accessories) on the same
+host machine where you are going to run fc-simint.  As of this writing, our FC
+SIM tools package has not yet reached the stage of first tarball release, hence
+you will need to get it from the Hg repository:
+
+https://www.freecalypso.org/hg/fc-sim-tools/
+
+FC SIM tools can be used by themselves (without FC host tools) if the objective
+is to operate on a SIM card using a dedicated smart card reader/programmer
+device.  However, if the SIM card to be operated on sits inside a Calypso phone
+or development board and you would like to poke at it without physically moving
+it back and forth between that Calypso device and another card reader, then
+fc-simint from the present package and fc-simtool from FC SIM tools work
+together to accomplish this feat.
+
+Once you have both FC host tools and FC SIM tools fully and properly installed,
+you are ready to run fc-simint.  fc-simint works in exactly the same manner as
+fc-loadtool (operates on the Calypso device, in this case the SIM interface
+rather than the flash, while the regular firmware is shut down), and it needs
+to be invoked in exactly the same way: simply change fc-loadtool to fc-simint.
+Some examples:
+
+SIM card in a Mot C139/140 phone:   fc-simint -h compal -c 1004 /dev/ttyUSBx
+SIM card in a Pirelli DP-L10 phone: fc-simint -h pirelli /dev/ttyUSBx
+SIM card in a FreeCalypso board:    fc-simint -h fcfam /dev/ttyUSBx
+
+If your USB-serial chip and the associated Linux kernel driver support
+non-standard high baud rates, you can add a -B812500 option to the above command
+lines to speed up the UART communication between fc-simint/fc-simtool on your
+host machine and simagent on the Calypso.  This speed-up option should always be
+safe with Pirelli DP-L10 and with FreeCalypso hardware (official FT2232x adapter
+boards), but the headset jack serial cables used with Mot C1xx phones are more
+iffy.
+
+The phone's regular firmware needs to be shut down, and you need to execute the
+Calypso device's boot path.  (For very advanced users, target boot control
+options work exactly the same way as in fc-loadtool.)  fc-simint will feed
+simagent.srec to the Calypso boot ROM, simagent will run on the Calypso device,
+and then fc-simint will command simagent to bring up the SIM interface.
+fc-simint will retrieve the SIM card's ATR from simagent, it will turn on speed
+enhancement if the SIM supports it, and then all further control is passed to
+fc-simtool.
+
+Once the control is passed to fc-simtool, you will see a simtool> prompt -
+please refer to fc-simtool documentation in the FC SIM tools package for the
+available commands such as manipulating SIM PINs and phonebooks.  Once you are
+done poking at the SIM card, type "exit" at the simtool> prompt - when operating
+in Calypso target mode, fc-simtool will issue a poweroff command to simagent
+just like fc-loadtool, causing most Calypso devices to power off cleanly, or
+causing the Pirelli DP-L10 phone to boot back into its regular firmware.
+
+Using fc-simtool batch mode via fc-simint
+=========================================
+
+If your fc-simint invokation line has any additional arguments after the
+/dev/ttyXXX Calypso target pathname, these arguments are passed to fc-simtool,
+causing it to operate in its batch mode instead of the default interactive
+shell.  However, given the logistics of operating on a Calypso device with its
+regular firmware shut down, this batch mode of operation is expected to be
+useful only in very unusual scenarios.
+
+Using fc-uicc-tool
+==================
+
+There are two main tools in the FC SIM tools package: fc-simtool speaks the
+classic GSM 11.11 SIM protocol to the card, whereas fc-uicc-tool speaks the
+"enemy" UICC protocol.  All currently existing Calypso phone and modem firmwares
+(both our own FreeCalypso and historical proprietary ones) speak only the
+classic GSM 11.11 SIM protocol, hence if you are using a given SIM in a Calypso
+phone or modem board, the expectation is that the card needs to support the
+classic GSM SIM application.  For this reason, fc-simtool is the tool of primary
+interest in this mode of usage, and it is the tool which fc-simint invokes by
+default.  In contrast, fc-uicc-tool is meant to be used primarily in lab
+exploration settings, with the card under investigation inserted into a
+dedicated smart card reader/programmer, not involving Calypso GSM devices or
+fc-simint.
+
+However, if you have a special contrived use case where you would like to run
+fc-uicc-tool on a SIM card that sits in a Calypso phone or other GSM device, you
+can do so by adding a -T uicc option to your fc-simint invokation line.  This
+option will make fc-simint pass the control to fc-uicc-tool instead of
+fc-simtool.
+
+Other fc-simint options
+=======================
+
+fc-simint supports all command line options documented in the Loadtools-usage
+article that are relevant to its operation.  There are just two more options
+that haven't been documented already:
+
+-n
+
+	This option suppresses SIM speed enhancement.  By default fc-simint
+	looks at the ATR TA1 byte to see if the SIM supports F=512 D=8 speed
+	enhancement (the only speed enhancement mode endorsed by the original
+	GSM SIM specs and supported by Calypso hardware), and requests this
+	speed enhancement mode if it is supported.  -n option suppresses the
+	latter action, forcing the default slow speed mode (F=372 D=1)
+	regardless of ATR-indicated SIM capabilities.
+
+-v volt
+
+	The volt argument needs to be "1.8" or "3.0" ("3" is also accepted as an
+	alias for 3.0), selecting the voltage mode in which the SIM should be
+	powered up.  3.0 V mode (not 3.3 V!) is class B per the specs, 1.8 V
+	mode is class C.  Class A is 5.0 V, but the Iota ABB chip in our Calypso
+	target devices (the chip responsible for SIM voltage supply and level
+	shifting) is new enough to not support that original class any more.
+	In the absence of a -v option, fc-simint currently uses 3.0 V mode by
+	default.