RFC: GSM flowcontrol handling, GTA01 and GTA02

[Mike (mwester)]

A mechanism is required that ensures that the GSM modem wakeup is handled 
correctly and completely by the kernel, for both the GTA01 and GTA02 devices.

----------

The requirements were first expressed by Harald Welte early in the project, and 
are outlined on the wiki: 
http://wiki.openmoko.org/wiki/GTA01_gsm_modem#Wakeup_of_CPU_from_GSM_Modem 
(especially the section titled "Software implementation").

Additional discussion has occurred on the openmoko-devel list, starting with 
this thread: 
http://lists.openmoko.org/pipermail/openmoko-devel/2008-March/002274.html
(Especially these emails in the thread:
http://lists.openmoko.org/pipermail/openmoko-devel/2008-March/002292.html
http://lists.openmoko.org/pipermail/openmoko-devel/2008-March/002294.html)

Additional to these comments are some comments and observations I made on an 
earlier email, especially with regard to race conditions and lost GSM 
interrupts, and the specific means to signal the events described above from the 
process managing the GSM to the kernel. 
(http://lists.openmoko.org/pipermail/openmoko-kernel/2008-May/002819.html)

----------

With that background, I propose that we modify the kernel for the GTA01 and 
GTA02 to implement the necessary mechanisms:

A) During suspend, the RTS line from the S3C24xx UART to the GSM shall be 
switched to a GPIO to forcibly assert flow-control to the GSM.  This ensures 
that the GSM will interrupt when it has data, and also ensures that the state of 
the flow-control signal will remain constant when the processor is in the 
suspend state (the state of this signal is guaranteed for GPIOs, but no 
documentation suggests that the state of the signal remains in any particular 
state for UART outputs while suspended).  During resume, the RTS line will be 
returned to the UART, where it can be handled in the normal fashion by the UART 
and the serial driver.

B) The preferred means for user-space programs to signal the kernel that the GSM 
should be forcibly flow-controlled in the fashion described above will be for 
the user-space program to make use of the TERMIO mechanism on the serial port to 
assert and de-assert RTS.  Power-state-aware GSM management programs will find 
this means to be the easiest (and probably the most portable).

C) From a practical point-of-view (neither gsmd nor qtopia presently use the 
TERMIO mechanism, and it is also useful for debugging purposes), a sysfs-based 
mechanism should exist to permit user-space to both determine the current status 
of the forced flowcontrol, and to enable or disable this forced flowcontrol. 
This mechanism can be easily used from apmd, for example.

D) A mechanism-of-last-resort would be desirable; this would be triggered during 
suspend by the GSM power-management driver to automatically force flow-control 
if no other mechanism has done so.

E) If an interrupt occurs after one of the above mechanisms forcibly 
flow-controls the GSM but before the system has actually completed the suspend 
process, the suspend process should detect that this has happened, and abort the 
suspend.  This is necessary in order to avoid the race-condition where a GSM 
interrupt can be missed when it occurs in this time-period.  A counter will be 
cleared when flow-control is forcibly asserted.  Code in the GSM interrupt 
handler will increment this counter with each GSM interrupt.  The GSM 
power-management driver will implement a late-suspend callback which will test 
the counter for a non-zero value, and abort the suspend in that case.  The 
aborted suspend will be, for all practical purposes, indistinguishable from an 
immediate resume event.

F) Upon resume, the value of the GSM interrupt counter should be made available 
to user-space via the sysfs.  This flag may be useful to the application stack 
to provide priority to the program managing the GSM, for example.  Note that the 
wakeup-reason recorded in sysfs (added by a recent kernel and uboot patch) may 
often serve this same purpose -- but not always.  The wakeup-reason will be 
invalid if the suspend never actually happened (because it was interrupted by 
the GSM=, as described above), or the wakeup-reason may be valid but the GSM 
interrupted very shortly after some other event woke the host processor (and 
thus was not the event that cause the wake-up, but still may require priority 
processing, for example).

----------

The impact of this on the existing kernels and applications is minimal.  The 
kernel logic to make these changes can (and should) be constrained to UART 0 on 
both GTA01 and GTA02.  At this time, neither gsmd nor qtopia use any of the 
pro-active mechanisms to use the new flowcontrol handling.  A cursory 
examination of the qtopia source code suggests that this might be a very easy 
change to implement, however.  Making gsmd power-state-aware is neither easy nor 
practical, however it is simple to use the apmd mechanisms to implement very 
acceptable power-state management using the libgsmd-tool and the sysfs interface 
to the new flowcontrol handling.  In either case, the fallback technique 
described above provides some marginal improvement in GSM handling without any 
changes other than the kernel itself.

----------

A set of patches that implements the described changes is available.  These 
patches are part of a set of patches suitable for the GTA01 and GTA02 devices 
with the old (non-ASU) rootfs.  Also available is a patched neod and the config 
files for apmd that make the GTA01 and GTA02 work* correctly as described by the 
requirements at the top of this document.

* disclaimer: there are still other suspend/resume issues that preclude full 
functionality; specifically there remains an issue with lack of audio to the 
speaker on the GTA01 post-resume, and there remain issues with the GTA02 failing 
to resume if left in suspend for a long time -- these issues are independent of 
the above RFC and sample patches, and need to be investigated and fixed separately.

Patch tarball: http://moko.mwester.net/mw09_kernel_patches.tgz
Readme:        http://moko.mwester.net/readme_kernel_mw09.txt
APM changes:   http://moko.mwester.net/mw09_apmstuff.tgz

(Prebuilt kernels are also available for download at that site.)

----------

I look forward to useful feedback on this approach.  I also welcome the 
opportunity to work to get this technique working in the Qtopia framework, as 
well as with future GSM management techniques.

Regards,
Mike