freecalypso-tools: doc/Target-utils comparison

comparison doc/Target-utils @ 528:81a3fc069301

doc/Target-utils: ABB support documented

author	Mychaela Falconia <falcon@freecalypso.org>
date	Sun, 16 Jun 2019 05:53:04 +0000
parents	aa4f70e36cbd
children	30bec872824a

comparison

equal deleted inserted replaced

-:aa4f70e36cbd
+:81a3fc069301
 designed, otherwise they will be longer.  In the case of pirexplore the strict
 timing requirement is satisfied by loading and running the program via fc-iram
 -h pirelli, resulting in the correct 52 MHz clock configuration; in all other
 cases running at a frequency below 52 MHz or running out of flash (the
 flash-boot-test special case) produces longer-than-needed delays.
+Common interactive commands
+===========================
+The exact set of implemented commands is different for each target-utils
+program, including commands specific to each program's unique function, but the
+following basic commands are included in most programs:
+abbinit			Initialize ABB communication
+abbpage2		Unlock access to ABB register page 2
+abbr pg reg		Read ABB register <reg> on page <pg>
+abbw pg reg val		Write <val> into register <reg> on page <pg>
+dump hex-start hex-len	Display a human-oriented memory dump in hex and ASCII
+jump addr		Jump to given address with BX
+poweroff		Execute Iota ABB soft poweroff (DEVOFF)
+r8 addr			Read an 8-bit register or memory location
+r16 addr		Read a 16-bit register or memory location
+r32 addr		Read a 32-bit register or memory location
+w8 addr data		Write an 8-bit register or memory location
+w16 addr data		Write a 16-bit register or memory location
+w32 addr data		Write a 32-bit register or memory location
+For further details, please refer to the source code - if you are playing with
+such low-level components, you need to put on the hat of a developer rather
+than a mere user.
+ABB support in target-utils
+===========================
+Our target-utils suite includes code for initializing and executing SPI
+communication with the Iota ABB device (TWL3014 or TWL3025), Calypso's analog
+and power management companion chip.  Only Iota ABB type is supported, not
+Omega/Nausica or Syren.  The primary reason for having this infrastructure is
+to be able to perform a soft poweroff operation, i.e., to return the Calypso
+phone or modem to its switched-off state after flashing or various standalone
+debug operations, but once implemented, this same ABB SPI communication
+infrastructure is also used in model-specific hardware exploration utilities
+for functions like keypad backlight and vibrator control which are implemented
+via the ABB on some models, and it is used in simtest to control the part of
+the SIM interface that resides in the Iota ABB.
+Aside from specialized programs like c139explore that are specific to target
+devices known to use the Iota ABB, most target-utils programs do not execute
+any ABB or SPI communication code (not even initialization) until they receive
+one of the ABB commands: abbinit, abbr, abbw or poweroff.  This way if someone
+comes across a Calypso device that has a different ABB type or needs to debug a
+board with broken ABB communication, one can explore other functions without
+touching ABB commands.
+The abb_init() function invoked by the abbinit command may be invoked multiple
+times: it maintains an internal flag remembering if the initialization steps
+have already been done or not, and repeated invokations do nothing.  User-
+friendly abbr, abbw and poweroff commands invoke abb_init() internally, but the
+special abbpage2 command does not - if you are interested in exploring the
+undocumented register page 2, you need to execute abbinit manually first, then
+abbpage2, then explore with abbr and abbw.
+poweroff operation details: VRPCAUX and VRPCDEV
+===============================================
+The abb_power_off() function invoked by the poweroff command performs the
+following sequence of steps:
+* Calls abb_init() to establish ABB communication in the case that it hasn't
+already been done;
+* Executes the magic writes to TAPCTRL and TAPREG registers that unlock access
+to register page 2 - this step is factored out into the abb_unlock_page2()
+function which is also accessible as the abbpage2 command;
+* Writes 0x007 into the undocumented VRPCAUX register to clear the erratic
+state that will be there if we got booted via nTESTRESET rather than PWON;
+* Flushes all UART output, i.e., waits for it to finish going out on the wire;
+* Writes 0x001 into the VRPCDEV register, which is the actual DEVOFF command.
+The step of writing into VRPCAUX and its prerequisite page 2 unlock steps are a
+recent addition as of fc-host-tools-r11; these steps have been added to fix the
+erratic behaviour that was occurring on TI/FC development boards (D-Sample and
+FCDEV3B) when fc-loadtool (or fc-iram with some specialized target-utils
+program) was entered via the RESET button rather than PWON, followed by the
+soft poweroff operation and another switch-on via PWON.  For more details,
+please refer to the Calypso-test-reset article in the freecalypso-docs
+repository.
+If you are interested in doing some experiments of your own with this
+undocumented quirk of the Calypso+Iota chipset and the odd behaviour it can
+cause, you can do the following:
+* To see the content of the undocumented VRPCAUX register resulting from
+different boot modes, execute these commands:
+abbinit
+abbpage2
+abbr 2 30
+Our abbr and abbw commands support page 2, but if you don't issue the magic
+register writes encapsulated in the abbpage2 command, the Iota chip itself
+disallows access to page 2.
+* To perform a DEVOFF operation without cleaning up VRPCAUX first (to see the
+resulting erratic behaviour with your own eyes), do it manually as follows:
+abbw 0 30 1
+flash-boot-test
+===============

FreeCalypso > hg > freecalypso-tools

comparison doc/Target-utils @ 528:81a3fc069301