Docs/gnokii-hackers-howto

   1 GNOKII Hackers Guide
   2 --------------------
   3
   4
   5 Purpose
   6 -------
   7
   8 Now that we know in some detail the workings of the protocols it makes
   9 sense to organise the gnokii code to fit them better.  This should mean
  10 that when new models come out, it is easier to get the code in place to
  11 support them.  It is hoped that the new structure will also work for other
  12 makes of phone.
  13
  14
  15 Overview:
  16
  17 Application (gnokii/xgnoki)
  18     |  DoSomething()
  19 (Middle-layer)
  20     |  GSM->Function()
  21 Gsm-api
  22     |  P*_Functions()
  23 Phone specific code (eg nk7110.c)
  24     |  SM_SendMessage(), SM_Wait(), SM_Loop()
  25 StateMachine
  26     |  SendMessage(), Loop()
  27 Link specific code  (eg fbus.c)
  28     |
  29 Hardware code
  30
  31
  32
  33 Detailed operation
  34 ------------------
  35
  36
  37 Initialisation:
  38
  39 The gnokii application (eg gnokii, xgnokii) decides on the phone type and
  40 required connection method from the config file.  It then calls the
  41 gsm-api init code which in turn calls the init code for the correct phone.
  42 This code is located in a series of files phone/*.c.  This code creates a
  43 GSM_State structure (which contains a GSM_Link structure) and passes this
  44 to the common code for the specific link (eg FBUS_Initialise, contained in
  45 fbus.c).  The link code fills in the GSM_Link part of state (and
  46 also stores state to use later).  The phone code chooses the appropriate
  47 link and is free to perform any phone specific init.  It then initialises
  48 the StateMachine by passing it the state struct and a GSM_Phone struct.
  49
  50
  51 The Link:
  52
  53 The link serves to deal with bits of the phone protocol which are common to
  54 every exchange for that particular phone.
  55
  56 The GSM_Link structure is used to contain any information about the link
  57 which is required by the StateMachine.  Two vital functions in the link
  58 are SendMessage and Loop:
  59
  60 SendMessage(u16 messagesize, u8 messagetype, void *message)
  61    is the function called by the statemachine code to send a message 'down
  62    the pipe'.  The parameters are intended to be generic (though with
  63    obvious origins :-)  For example 'at' commands could be enumerated and
  64    passed as messagetype.
  65
  66 Loop(struct timeval *timeout)
  67    is a function which must be called regularly by the statemachine code
  68    to enable to link code to process date from the phone.  This is due to
  69    the code now being single threaded and using select/poll.  The timeout
  70    passed can therefore be used to make this function block for a while
  71   (or not).
  72
  73 In the loop function, the link code checks for any incoming messages from
  74 the phone.  Any received correctly are passed up to the statemachine code.
  75
  76
  77 The Middle Layer
  78
  79 All common/*.c files contain the code that is general and is used by all
  80 of the phones. The functions within should convert the gnokii internal
  81 structures into the frames (without the header) that can be sent to the
  82 phone and understood by it. It's obvious that this layer should be phone
  83 independent. All the phone specific stuff should be done in the phone layer.
  84 In the case when phone frames are similiar but not the same, the phone layer
  85 can export some help structures to let be the code shared in the middle
  86 layer. Using the middle layer is optional. Currently almost no code does use
  87 it. Although it is recommended to use it to avoid the code duplication and
  88 to keep clean the phone drivers.
  89
  90
  91 The Phone:
  92
  93 The phone/*.c code therefore basically contains code to package up and
  94 unpack information from the phone specific format to generic gnokii
  95 structures (eg GSM_Bitmap).  However, it is also at the top of the tree
  96 and contains functions called by the application.  Generally there are
  97 three types of exchanges that can occur.  Firstly the computer can send
  98 the phone a command and expect no answer (not including acks etc which
  99 are dealt with by the phone code).  Secondly the computer may send a command
 100 and expect a response within a certain time - often containing useful
 101 information.  Lastly the phone may send the computer unrequested
 102 information (ring!).  Therefore the functions in the phone code need to
 103 process one of these three things:
 104
 105 1) Just sending out is easy - we simply call SM_SendMessage - which in
 106 turn calls the link sendmessage.
 107
 108 2) Command and response.  There are two ways to do this.  In both cases we
 109 start out by sending a message via the statemachine.  Next we either a)
 110 wait for the reply or b) wait for some other code to process the reply.
 111 My (*new improved*!!!) suggestion is that the statemachine calls phone
 112 functions (like parts of DispatchMessage) which process the received data
 113 into a generic structure tagged with the data type (one function for each
 114 data type).  This is returned to the statemachine.  The statemachine then
 115 returns this 'baggage' to the other part of the phone code which is
 116 waiting for it.
 117
 118 3) Notification.  Here, as for 2) the statemachine calls some phone code,
 119 but the phone code merely remembers it and does not return any data.
 120
 121
 122 So, the phone file contains two types of functions.  Some are called by
 123 the application (via GSM_Functions) - and some by the statemachine
 124 (IncomingFunctions[]).  The application ones assemble a request and pass
 125 it on down to the statemachine.  They then block to the statemachine until
 126 the answer is ready.  The statemachine recieves data from the link and
 127 passes it up to the appropriate IncomingFunction in phone, which returns
 128 the answer which is finally passed back to the blocked phone function.
 129
 130
 131 The StateMachine:
 132
 133 This therefore has the following states:
 134
 135 Startup
 136 Initialised
 137 MessageSent
 138 Waiting
 139 AnswerReady
 140
 141 When SM_SendMessage is called by the phone (application code), we go to
 142 state MessageSent.  The message is passed on to the link, but stored
 143 internally as well in-case it needs to be resent.
 144
 145 If at any point an message from the link is received this is passed onto
 146 the phone (incoming) code.
 147
 148 If the phone code calls SM_WaitFor, we go to state Waiting.  Now if an
 149 answer comes back from the phone code (eg a received logo) we store it
 150 internally in the statemachine and go to state AnswerReady.
 151
 152 When the phone code calls SM_GetAnswer, we pass up the stored answer and
 153 go back to Initialised.
 154
 155 Note that all of this can, or can not be done as a seperate thread.  For
 156 now, we will have a SM_Loop function (which blocks for a required time and
 157 returns the current state) so that we can work within one thread.
 158
 159
 160 PhoneGeneric:
 161
 162 This now contains one handy helper function which serves only to call
 163 SM_WaitFor, then SM_Loop repeatedly until the state goes to AnswerReady,
 164 and then SM_GetAnswer.  This is just to save repeating code.
 165
 166
 167 -----------------------
 168
 169 Note that this leaves the phone code very similar to the basic layout of
 170 eg fbus-6110.c but removes all the:
 171
 172 static GSM_DateTime       *CurrentAlarm;
 173 static GSM_Error          CurrentAlarmError;
 174
 175 ,makes everything well orderd and splits up DispatchMessage into byte
 176 sized chunks!
 177
 178 -----------------------
 179
 180
 181
 182 Other Notes
 183 -----------
 184
 185 Within a phone/*.c or link file the functions should be made static.  It
 186 is therefore not necessary to use prefixes such as FB61_ but this may help
 187 code legibility to distiguish the major functions.
 188
 189
 190 --
 191 $Id$
 192 Chris Kemp
 193 Pawel Kot