CHANGES: document lunadrv init-kwh addition
author
Mychaela Falconia <falcon@freecalypso.org>
date
Tue, 22 Jun 2021 02:28:18 +0000 (2021-06-22)
parents
f33d050eac6e
children
line source
+ − Building and installing FreeCalypso host tools
+ − ==============================================
+ −
+ − Our FreeCalypso host tools are designed to be installed in the /opt/freecalypso
+ − directory hierarchy on your system. The author of this software is very
+ − old-fashioned and refuses to use autotools (sorry, we aren't GNU), hence
+ − various hard-coded paths under /opt/freecalypso are sprinkled in bazillion
+ − places - thus changing this fixed install location is deemed to be impractical.
+ − See PACKAGING and doc/opt-freecalypso-tree for more notes on this subject.
+ −
+ − In order to compile and install our host tools, follow these steps:
+ −
+ − 1: Run 'make' as a regular user (not root) to compile the software.
+ −
+ − 2: Decide if you prefer to have the /opt/freecalypso directory and everything
+ − under it to be owned by root or by your non-root uid.
+ −
+ − If you prefer /opt/freecalypso to be root-owned:
+ −
+ − 3A: Run 'make install' as root; the install rule in the
+ − Makefile will do mkdir -p /opt/freecalypso as its first step.
+ −
+ − 4A: You are done!
+ −
+ − If you prefer /opt/freecalypso to be owned by your "regular" non-root uid:
+ −
+ − 3B: Become root just to create the /opt/freecalypso directory and chown it
+ − to your non-root uid.
+ −
+ − 4B: Run 'make install' as your regular uid; it should succeed because you
+ − should have made yourself the owner of /opt/freecalypso with full write
+ − permission in the previous step.
+ −
+ − 5B: You are done!
+ −
+ − The host tool binaries will be installed in /opt/freecalypso/bin; you can
+ − either add this directory to your PATH or make symlinks from /usr/bin or
+ − /usr/local/bin or wherever.
+ −
+ − Dependencies
+ − ============
+ −
+ − All FreeCalypso host tools are written in plain C and have absolutely no
+ − library dependencies beyond libc. In other words, they are very friendly to
+ − those who like bare bones minimalist systems.
+ −
+ − The previous dependency on OpenSSL libraries for DES decryption of the factory
+ − IMEI record on the Pirelli DP-L10 has been eliminated by incorporating our own
+ − simple DES implementation (performance is not a concern for the one time
+ − operation of retrieving the factory IMEI) into our rvinterf/etmsync source, and
+ − the functions that require access to Pirelli's IMEI have now been integrated
+ − into fc-fsio.
+ −
+ − Previous versions of this FC host tools package included a UI development aid
+ − utility called fc-lcdemu which needs libX11 to compile and an X11 display to
+ − run; this utility has now been moved to a separate freecalypso-ui-dev
+ − repository and is no longer a part of the core FC host tools package.
+ −
+ − CC= and CFLAGS= selection
+ − =========================
+ −
+ − Our Makefile hierarchy is set up to build with CC=gcc and CFLAGS=-O2 by default.
+ − If you need to change either or both of these selections, you can do it by
+ − adding CC= and/or CFLAGS= on the make invokation line, for example:
+ −
+ − make CC=mygcc CFLAGS="-g -O2 -whatever-options"
+ −
+ − libserial and Linux specifics
+ − =============================
+ −
+ − We have our own private library called libserial which contains our serial port
+ − handling code (serial ports are what we use to talk to Calypso GSM devices),
+ − and this library exists in several different versions. At the top level of our
+ − source tree libserial is a symlink to one of libserial-* versions.
+ −
+ − Starting with fc-host-tools-r7, the default version of libserial (i.e., the
+ − version to which the libserial symlink points in the official release source)
+ − is libserial-linux. This version of libserial has the advantage of supporting
+ − high GSM baud rates (see doc/High-speed-serial) with FTDI adapters without
+ − needing a dirty patch to the in-kernel driver, but it comes at the price of
+ − being very specific to Linux. If you would like to run FreeCalypso host tools
+ − under FreeBSD, illumos or some other alternative-to-Linux OS, see the section
+ − titled "Support for other Unix flavors" in the doc/High-speed-serial article.
+ −
+ − Target binaries
+ − ===============
+ −
+ − If you are installing a packaged release of FreeCalypso host tools, there will
+ − be a number of prebuilt target binaries (code to be run on the Calypso ARM7
+ − processor) in the target-bin directory; when you run make install as instructed
+ − above, these target binaries will be installed in /opt/freecalypso/target-bin.
+ − Otherwise, you will need to compile them yourself using an ARM7 toolchain as
+ − detailed below.
+ −
+ − Building and installing the ARM7 toolchain
+ − ==========================================
+ −
+ − The current "official" GNU ARM toolchain for FreeCalypso consists of
+ − binutils-2.21.1, gcc-4.5.4 and newlib-2.0.0 with a specific set of patches and
+ − build configuration options. This toolchain is used to compile target-utils in
+ − this package as well as our separately-maintained experimental FC Selenite
+ − firmware. (Our production firmwares are currently built with TI's TMS470
+ − toolchain instead.) Build it as follows:
+ −
+ − 1. Download these 3 source tarballs for the standard GNU+newlib components:
+ −
+ − binutils-2.21.1a.tar.bz2
+ − gcc-core-4.5.4.tar.bz2
+ − newlib-2.0.0.tar.gz
+ −
+ − 2. Run the build+install.sh script in the toolchain directory. Read the
+ − comments in the script first for the usage instructions.
+ −
+ − The toolchain thus built will need to be in your PATH before you can compile
+ − target-utils or FC Selenite. The officially recommended install location for
+ − this toolchain is /opt/freecalypso/gcc.
+ −
+ − Please note: the toolchain that is prescribed for FreeCalypso as above is
+ − *believed* to be equivalent to the one used by OsmocomBB, but there are no
+ − guarantees. Use any other toolchain at your own risk.
+ −
+ − Compiling target-utils
+ − ======================
+ −
+ − Running 'make' in the target-utils tree with the ARM7 toolchain present in your
+ − PATH will result in several target binaries being built, including compalstage
+ − and loadagent which are needed in order to use FreeCalypso loadtools. Run
+ − 'make install' to install these target binaries in /opt/freecalypso/target-bin,
+ − which is where loadtools will look for them.
+ −
+ − Run 'make all' in target-utils to build some additional target code pieces that
+ − are needed only for development and only very rarely.
+ −
+ − Staged installs
+ − ===============
+ −
+ − As already explained above, our FC host tools need to be installed under
+ − /opt/freecalypso on your system in order to function correctly, and this runtime
+ − location is not changeable. However, some users have requested an ability to
+ − do a staged install: have the 'make install' operation install the finished
+ − tree of files in some staging location, with the expectation that it will be
+ − subsequently moved to /opt/freecalypso by some other mechanism. One use case
+ − that has been presented to us was automated building of binary distribution
+ − packages on a build host where writing to /opt/freecalypso is not allowed.
+ −
+ − If you need to make a staged install of this sort, you can do it like this:
+ −
+ − make install INSTALL_PREFIX=/home/me/my-fc-staging-area
+ −
+ − Please note that this INSTALL_PREFIX= scheme changes *only* the location where
+ − 'make install' will deposit the installable files; it does NOT change the
+ − location where our programs will look for other programs and helper files: the
+ − latter location is hard-coded as /opt/freecalypso is bazillion places throughout
+ − our code base.