# HG changeset patch # User Mychaela Falconia # Date 1560664384 0 # Node ID 81a3fc069301c5fbc0cbb453285fbb92669fdf64 # Parent aa4f70e36cbd42940c00ea0429a4e3d6af3a7215 doc/Target-utils: ABB support documented diff -r aa4f70e36cbd -r 81a3fc069301 doc/Target-utils --- a/doc/Target-utils Fri Jun 14 08:30:54 2019 +0000 +++ b/doc/Target-utils Sun Jun 16 05:53:04 2019 +0000 @@ -130,3 +130,112 @@ -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 on page +abbw pg reg val Write into register on page +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 +=============== +