FreeCalypso > hg > fc-magnetite

comparison cdg3/sap/8010_136_SIMDRV_SAP.sap @ 16:c15047b3d00d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
cdg3: import from freecalypso-citrine/cdg
author Mychaela Falconia <falcon@freecalypso.org>
date Tue, 27 Sep 2016 16:27:34 +0000
parents
children
comparison
equal deleted inserted replaced
15:c8bdae60fcb1 16:c15047b3d00d
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- edited with SAPE SAP Editor -->
3 <SAP xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="sap.xsd">
4 <DocInfoSection>
5 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
6 <DocNum Number="136" Project="8010"/>
7 <Description>
8 <DocElement>
9 <XHTMLElement Type="TEXT_SECTION">The interface is function based only.</XHTMLElement>
10 </DocElement>
11 <DocElement>
12 <XHTMLElement Type="TEXT_SECTION">Throughout the document the term UICC is used to cover both a GSM SIM that contains one single application, the GSM application, and a multi-application UICC that contains one or more applications, maximum one GSM and one or more UMTS applications.</XHTMLElement>
13 </DocElement>
14 <DocElement>
15 <XHTMLElement Type="TEXT_SECTION">Data stores are used to transfer information between the SIM reader driver and the PS. Pointers to the data stores where the data is written to and read from are handed to the SIM reader driver by the PS. The format of the data stored in these stores are compliant to the format specified in [3G 11.11], [3G 11.14], [3G 31.102], [3G 31.111] and [ETSI 102 221]. Therefore, the formatting of data located in these stores are not described throughout this document. The same approach is used in regards to status words, etc. Only in the case where SIM data is reformatted, will they be described in this document.</XHTMLElement>
16 </DocElement>
17 <DocElement>
18 <XHTMLElement Type="TEXT_SECTION">Two functions are not defined in this document and are the two only functions called from the SIM driver to the PS. These are the SIM insertion and SIM removal functions. The first call after power-on, the simdrv_register function, gives two function pointers to the SIM driver for these two functions. Else, all function calls are initiated by the PS.</XHTMLElement>
19 </DocElement>
20 <DocElement>
21 <XHTMLElement Type="TEXT_SECTION">The transmission protocol is handled autonomously by the SIM reader driver. This means that the interface between the PS and SIM reader driver operates at APDU command level and that the PS has no knowledge of which protocol has been selected for communication between the SIM reader driver and the inserted UICC during the PPS procedure. Thus the PS is not required to perform the GET RESPONSE command, instead this is done, in case of protocol T=0, by the driver .</XHTMLElement>
22 </DocElement>
23 <DocElement>
24 <DocLink DocType="IMAGE">
25 <Name>8010_136_SIMDRV_SAP.vsd</Name>
26 <SubName>Page-1</SubName>
27 <EditCmdString>execmd --visio --show --createNew -f %p%n0 -p %n1</EditCmdString>
28 <ImageCmdString>execmd --visio --extract -f %p%n0 -p %n1 -d %p%n1.emf</ImageCmdString>
29 </DocLink>
30 </DocElement>
31 <DocElement>
32 <XHTMLElement Type="TEXT_SECTION">
33 <b>Figure 1-1: Interface overview.</b>
34 </XHTMLElement>
35 </DocElement>
36 <DocElement>
37 <XHTMLElement Type="TEXT_SECTION">Communication between the PS and the driver will always be initiated by the PS, with two exceptions to that rule.</XHTMLElement>
38 </DocElement>
39 <DocElement>
40 <XHTMLElement Type="LIST_ITEM_UNORDERED_START">When the PS asks the driver to reset the UICC, the driver uses a call back function that is handed during initialisation to inform the PS.</XHTMLElement>
41 </DocElement>
42 <DocElement>
43 <XHTMLElement Type="LIST_ITEM_END">When the inserted UICC is physically removed from the PS, the driver calls another call back function that is handed during initialisation</XHTMLElement>
44 </DocElement>
45 </Description>
46 <DocHistory>
47 <DocVersion Number="001" Year="03"/>
48 <Date Day="20" Month="1" Year="2003"/>
49 <Author>KKS</Author>
50 <DocStatus State="APPROVED"/>
51 <Comment>Initial version.</Comment>
52 </DocHistory>
53 <DocHistory>
54 <DocVersion Number="002" Year="03"/>
55 <Date Day="20" Month="1" Year="2003"/>
56 <Author>KKS</Author>
57 <DocStatus State="APPROVED"/>
58 <Comment>Document based on 7510.126.02.10</Comment>
59 </DocHistory>
60 <DocHistory>
61 <DocVersion Number="003" Year="03"/>
62 <Date Day="20" Month="1" Year="2003"/>
63 <Author>KKS</Author>
64 <DocStatus State="APPROVED"/>
65 <Comment>Group column in function prototype removed</Comment>
66 </DocHistory>
67 <DocHistory>
68 <DocVersion Number="004" Year="03"/>
69 <Date Day="26" Month="5" Year="2003"/>
70 <Author>KKS</Author>
71 <DocStatus State="APPROVED"/>
72 <Comment>Links to constants added</Comment>
73 </DocHistory>
74 <DocHistory>
75 <DocVersion Number="005" Year="03"/>
76 <Date Day="26" Month="5" Year="2003"/>
77 <Author>KKS</Author>
78 <DocStatus State="APPROVED"/>
79 <Comment>sim_ in function names changed to sl2_.</Comment>
80 </DocHistory>
81 <DocHistory>
82 <DocVersion Number="006" Year="03"/>
83 <Date Day="20" Month="8" Year="2003"/>
84 <Author>KKS</Author>
85 <DocStatus State="APPROVED"/>
86 <Comment>Function names in MSCs in section 6 changed from sim_ to sl2_</Comment>
87 </DocHistory>
88 <DocHistory>
89 <DocVersion Number="007" Year="03"/>
90 <Date Day="20" Month="11" Year="2003"/>
91 <Author>FK</Author>
92 <DocStatus State="BEING_PROCESSED"/>
93 <Comment>Revised</Comment>
94 </DocHistory>
95 <DocHistory>
96 <DocVersion Number="008" Year="03"/>
97 <Date Day="3" Month="5" Year="2004"/>
98 <Author>FDU</Author>
99 <DocStatus State="BEING_PROCESSED"/>
100 <Comment>Alignment according to review report.</Comment>
101 </DocHistory>
102 <DocHistory>
103 <DocVersion Number="009" Year="03"/>
104 <Date Day="10" Month="6" Year="2004"/>
105 <Author>FDU</Author>
106 <DocStatus State="BEING_PROCESSED"/>
107 <Comment>Alignment with agreements and review comments from meeting in Nice</Comment>
108 </DocHistory>
109 </DocInfoSection>
110 <PragmasSection>
111 <Description>
112 <DocElement>
113 <XHTMLElement Type="TEXT_SECTION">Defines maximum value used in parameter definitions</XHTMLElement>
114 </DocElement>
115 </Description>
116 <Pragma>
117 <Name>PREFIX</Name>
118 <Value ValueType="ALPHA">SIMDRV</Value>
119 <Comment>Prefix for this document</Comment>
120 </Pragma>
121 <Pragma>
122 <Name>ALLWAYS_ENUM_IN_VAL_FILE</Name>
123 <Value ValueType="ALPHA">YES</Value>
124 <Comment>Adds enumerations in the .val file.</Comment>
125 </Pragma>
126 <Pragma>
127 <Name>ENABLE_GROUP</Name>
128 <Value ValueType="ALPHA">YES</Value>
129 <Comment>Enable h-file grouping</Comment>
130 </Pragma>
131 <Pragma>
132 <Name>COMPATIBILITY_DEFINES</Name>
133 <Value ValueType="ALPHA">NO</Value>
134 <Comment>Compatible to the old #defines</Comment>
135 </Pragma>
136 <History>
137 <Date Day="20" Month="2" Year="2002"/>
138 <Author>FDU</Author>
139 <Comment>Initial</Comment>
140 </History>
141 <History>
142 <Date Day="30" Month="10" Year="2003"/>
143 <Author>FK</Author>
144 <Comment>'MAX_RESULT' corrected</Comment>
145 </History>
146 <History>
147 <Date Day="3" Month="5" Year="2004"/>
148 <Author>FDU</Author>
149 <Comment>PREFIX changed to SIMDRV</Comment>
150 </History>
151 </PragmasSection>
152 <ConstantsSection>
153 <Description>
154 <DocElement>
155 <XHTMLElement Type="TEXT_SECTION">Defines maximum value used in parameter definitions</XHTMLElement>
156 </DocElement>
157 </Description>
158 <Constant>
159 <Alias>SIZE_ATR_INFO</Alias>
160 <Value ValueType="HEX">21</Value>
161 <Group>uicc</Group>
162 <Comment>The maximum length of the data returned from the ATR procedure</Comment>
163 </Constant>
164 <Constant>
165 <Alias>MIN_RESULT</Alias>
166 <Value ValueType="HEX">01</Value>
167 <Group>uicc</Group>
168 <Comment>Minimum size of the response of any given command</Comment>
169 </Constant>
170 <Constant>
171 <Alias>MAX_RESULT</Alias>
172 <Value ValueType="HEX">100</Value>
173 <Group>uicc</Group>
174 <Comment>Maximum size of the response of any given command</Comment>
175 </Constant>
176 <Constant>
177 <Alias>MIN_DATA_SIZE</Alias>
178 <Value ValueType="HEX">01</Value>
179 <Group>uicc</Group>
180 <Comment>Minimum length of a data element</Comment>
181 </Constant>
182 <Constant>
183 <Alias>MAX_DATA_SIZE</Alias>
184 <Value ValueType="HEX">FF</Value>
185 <Group>uicc</Group>
186 <Comment>Maximum length of a data element</Comment>
187 </Constant>
188 <Constant>
189 <Alias>MAX_READERS</Alias>
190 <Value ValueType="HEX">02</Value>
191 <Group>uicc</Group>
192 <Comment>Maximum number of card readers supported.</Comment>
193 </Constant>
194 <History>
195 <Date Day="20" Month="2" Year="2002"/>
196 <Author>FDU</Author>
197 <Comment>Initial</Comment>
198 </History>
199 <History>
200 <Date Day="30" Month="10" Year="2003"/>
201 <Author>FK</Author>
202 <Comment>'MAX_RESULT' corrected</Comment>
203 </History>
204 <History>
205 <Date Day="3" Month="5" Year="2004"/>
206 <Author>FDU</Author>
207 <Comment>PREFIX changed to SIMDRV</Comment>
208 </History>
209 </ConstantsSection>
210 <PrimitivesSection PrimIDType="BIT32" SAPid="154">
211 <Description>
212 <DocElement>
213 <XHTMLElement Type="TEXT_SECTION">This section contains all primitives that are defined for the 8010_136_SIMDRV_SAP SAP</XHTMLElement>
214 </DocElement>
215 </Description>
216 <Primitive>
217 <Description>
218 <DocElement>
219 <XHTMLElement Type="TEXT_SECTION">Dummy.</XHTMLElement>
220 </DocElement>
221 </Description>
222 <PrimDef>
223 <Name>SIMDRV_DUMMY</Name>
224 <PrimID Direction="UPLINK" Number="255"/>
225 <PrimUsage>
226 <Sender>SIM</Sender>
227 <Receiver>DRIVER</Receiver>
228 </PrimUsage>
229 <Group>uicc</Group>
230 </PrimDef>
231 <PrimItem Presentation="MANDATORY">
232 <ItemLink>
233 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
234 <Name>atr_string_info</Name>
235 </ItemLink>
236 <Control>PTR</Control>
237 <Comment>SIM Card Info</Comment>
238 </PrimItem>
239 <PrimItem Presentation="MANDATORY">
240 <ItemLink>
241 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
242 <Name>reset_return_val</Name>
243 </ItemLink>
244 <Comment>Return Value</Comment>
245 </PrimItem>
246 <PrimItem Presentation="MANDATORY">
247 <ItemLink>
248 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
249 <Name>result_info</Name>
250 </ItemLink>
251 <Control>PTR</Control>
252 <Comment>Result Buffer</Comment>
253 </PrimItem>
254 <PrimItem Presentation="MANDATORY">
255 <ItemLink>
256 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
257 <Name>len</Name>
258 </ItemLink>
259 <Comment>Length of expected data</Comment>
260 </PrimItem>
261 <PrimItem Presentation="MANDATORY">
262 <ItemLink>
263 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
264 <Name>data_info</Name>
265 </ItemLink>
266 <Control>PTR</Control>
267 <Comment>Update Data Element</Comment>
268 </PrimItem>
269 <PrimItem Presentation="MANDATORY">
270 <ItemLink>
271 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
272 <Name>sw1_2</Name>
273 </ItemLink>
274 <Comment>Status Words</Comment>
275 </PrimItem>
276 <PrimItem Presentation="MANDATORY">
277 <ItemLink>
278 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
279 <Name>cla</Name>
280 </ItemLink>
281 <Comment>Class Byte</Comment>
282 </PrimItem>
283 <PrimItem Presentation="MANDATORY">
284 <ItemLink>
285 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
286 <Name>ins</Name>
287 </ItemLink>
288 <Comment>Instruction Code</Comment>
289 </PrimItem>
290 <PrimItem Presentation="MANDATORY">
291 <ItemLink>
292 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
293 <Name>cmd_header</Name>
294 </ItemLink>
295 <Comment>Transparent command header</Comment>
296 </PrimItem>
297 <PrimItem Presentation="MANDATORY">
298 <ItemLink>
299 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
300 <Name>voltage_select</Name>
301 </ItemLink>
302 <Comment>Perform Voltage Selection</Comment>
303 </PrimItem>
304 <PrimItem Presentation="MANDATORY">
305 <ItemLink>
306 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
307 <Name>p1</Name>
308 </ItemLink>
309 <Comment>SIM Command Parameters</Comment>
310 </PrimItem>
311 <PrimItem Presentation="MANDATORY">
312 <ItemLink>
313 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
314 <Name>p2</Name>
315 </ItemLink>
316 <Comment>SIM Command Parameters</Comment>
317 </PrimItem>
318 <PrimItem Presentation="MANDATORY">
319 <ItemLink>
320 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
321 <Name>config_requested</Name>
322 </ItemLink>
323 <Comment>Configuration Characteristics requested</Comment>
324 </PrimItem>
325 <PrimItem Presentation="MANDATORY">
326 <ItemLink>
327 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
328 <Name>config_characteristics</Name>
329 </ItemLink>
330 <Control>PTR</Control>
331 <Comment>Configuration Characteristics</Comment>
332 </PrimItem>
333 <PrimItem Presentation="MANDATORY">
334 <ItemLink>
335 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
336 <Name>reader_id</Name>
337 </ItemLink>
338 <Comment>Reader Id</Comment>
339 </PrimItem>
340 <PrimItem Presentation="MANDATORY">
341 <ItemLink>
342 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
343 <Name>uicc_characteristics</Name>
344 </ItemLink>
345 <Comment>UICC Characteristics</Comment>
346 </PrimItem>
347 <History>
348 <Date Day="9" Month="12" Year="2002"/>
349 <Author>BRY</Author>
350 <Comment>Initial version after merge.</Comment>
351 </History>
352 <History>
353 <Date Day="20" Month="11" Year="2003"/>
354 <Author>FK</Author>
355 <Comment>New prefix; changes in section 5.</Comment>
356 </History>
357 <History>
358 <Date Day="8" Month="12" Year="2003"/>
359 <Author>FK</Author>
360 <Comment>Revised</Comment>
361 </History>
362 <History>
363 <Date Day="3" Month="5" Year="2004"/>
364 <Author>FDU</Author>
365 <Comment>Aligned with contents of chapter 4 and chapter 5</Comment>
366 </History>
367 <History>
368 <Date Day="10" Month="6" Year="2004"/>
369 <Author>FDU</Author>
370 <Comment>Aligned with contents of chapter 4 and chapter 5</Comment>
371 </History>
372 </Primitive>
373 </PrimitivesSection>
374 <FunctionsSection>
375 <Description>
376 <DocElement>
377 <XHTMLElement Type="TEXT_SECTION">This section contains all functions that are defined for the 8010_136_SIMDRV_SAP SAP</XHTMLElement>
378 </DocElement>
379 </Description>
380 <Function>
381 <Description>
382 <DocElement>
383 <XHTMLElement Type="TEXT_SECTION">This function is used to inform the SIM reader driver that it shall deactivate. Nothing is passed to the SIM hardware driver, neither is something returned.</XHTMLElement>
384 </DocElement>
385 </Description>
386 <FuncDef IsLinkTarget="NO">
387 <Name>poweroff</Name>
388 <FuncUsage>
389 <Caller>SIM</Caller>
390 <Callee>DRIVER</Callee>
391 </FuncUsage>
392 </FuncDef>
393 <FuncArg>
394 <ItemLink>
395 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
396 <Name>reader_id</Name>
397 </ItemLink>
398 <Comment>Reader Id</Comment>
399 </FuncArg>
400 <History>
401 <Date Day="20" Month="2" Year="2002"/>
402 <Author>FDU</Author>
403 <Comment>Initial.</Comment>
404 </History>
405 <History>
406 <Date Day="20" Month="11" Year="2003"/>
407 <Author>FK</Author>
408 <Comment>Prefix changed; description extended.</Comment>
409 </History>
410 <History>
411 <Date Day="3" Month="5" Year="2004"/>
412 <Author>FDU</Author>
413 <Comment>function renamed</Comment>
414 </History>
415 <History>
416 <Date Day="10" Month="6" Year="2004"/>
417 <Author>FDU</Author>
418 <Comment>reader id added</Comment>
419 </History>
420 </Function>
421 <Function>
422 <Description>
423 <DocElement>
424 <XHTMLElement Type="TEXT_SECTION">The PS uses this function to make the driver attempt a reset of the inserted UICC and to start card session.</XHTMLElement>
425 </DocElement>
426 <DocElement>
427 <XHTMLElement Type="TEXT_SECTION">If the driver does not detect the presence of a SIM card, then it shall return the value SIM_NOT_INSERTED.</XHTMLElement>
428 </DocElement>
429 <DocElement>
430 <XHTMLElement Type="TEXT_SECTION">If the driver is able to successfully initialise the card and start a card session, it calls the call-back function 'insert()' with the appropriate parameters. After regaining control from the call-back function the driver finishes the reset function and returns the value SIM_INSERTED.</XHTMLElement>
431 </DocElement>
432 <DocElement>
433 <XHTMLElement Type="TEXT_SECTION">The function has a parameter which is used to indicate to the SIM reader driver whether or not the SIM reader driver shall reset the card performing the voltage selection procedure or reset the card using the current voltage class.</XHTMLElement>
434 </DocElement>
435 </Description>
436 <FuncDef IsLinkTarget="NO">
437 <Name>reset</Name>
438 <FuncUsage>
439 <Caller>SIM</Caller>
440 <Callee>DRIVER</Callee>
441 </FuncUsage>
442 </FuncDef>
443 <FuncRet>
444 <ItemLink>
445 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
446 <Name>reset_return_val</Name>
447 </ItemLink>
448 <Comment>Function return value</Comment>
449 </FuncRet>
450 <FuncArg>
451 <ItemLink>
452 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
453 <Name>reader_id</Name>
454 </ItemLink>
455 <Comment>Reader Id</Comment>
456 </FuncArg>
457 <FuncArg>
458 <ItemLink>
459 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
460 <Name>voltage_select</Name>
461 </ItemLink>
462 <Comment>Perform voltage selection</Comment>
463 </FuncArg>
464 <History>
465 <Date Day="20" Month="2" Year="2002"/>
466 <Author>FDU</Author>
467 <Comment>Initial.</Comment>
468 </History>
469 <History>
470 <Date Day="16" Month="12" Year="2002"/>
471 <Author>FDU</Author>
472 <Comment>Parameters changed to pure struct pointers.</Comment>
473 </History>
474 <History>
475 <Date Day="3" Month="5" Year="2004"/>
476 <Author>FDU</Author>
477 <Comment>function renamed, parameters aligned to review report</Comment>
478 </History>
479 <History>
480 <Date Day="10" Month="6" Year="2004"/>
481 <Author>FDU</Author>
482 <Comment>reader id added</Comment>
483 </History>
484 </Function>
485 <Function>
486 <Description>
487 <DocElement>
488 <XHTMLElement Type="TEXT_SECTION">Used to transparently exchange APDU commands and result with any application, which may reside on the SIM. If the communication between SIM and ME is run by the protocol T=0, then the functions performs autonomously the GET RESPONSE Command observing the following rule:</XHTMLElement>
489 </DocElement>
490 <DocElement>
491 <XHTMLElement Type="LIST_ITEM_UNORDERED_START">If the card responds with SW1=9F, then the command shall be coded as described in [GSM 11.11].</XHTMLElement>
492 </DocElement>
493 <DocElement>
494 <XHTMLElement Type="LIST_ITEM_END">If the card responds with SW1=61, then the command shall be coded as described in [ETSI TS 102 221].</XHTMLElement>
495 </DocElement>
496 <DocElement>
497 <XHTMLElement Type="TEXT_SECTION">The function complies with the following rules for the interpretation of its parameters:</XHTMLElement>
498 </DocElement>
499 <DocElement>
500 <XHTMLElement Type="LIST_ITEM_UNORDERED_START">Access to a NULL pointer, either read or write, must not be performed. If this leads to a contradiction (i.e. a data count is given, but the null pointer prevents access to the data), then the function shall return SIMDRV_ERR_PARAM_WRONG.</XHTMLElement>
501 </DocElement>
502 <DocElement>
503 <XHTMLElement Type="LIST_ITEM">If parameter 'result_info' is set to ZERO or its element 'len' is set to ZERO, then the driver shall not read data from the card. If the card answers with SW1=61/9F, then this result code is passed to the caller, but GET RESPONSE is not performed.</XHTMLElement>
504 </DocElement>
505 <DocElement>
506 <XHTMLElement Type="LIST_ITEM">If the element 'len' of parameter 'result_info' is set to NON-ZERO, then the driver shall try to read up to 'len' bytes from the card. The data is stored in element 'result', the count element receives the number of actually read bytes. In case of protocol T=0 the element 'len' is identical with parameter P3, in case of protocol T=1 it is identical with parameter Le. If the UICC responds with SW1=6C and a requested size larger than indicated in 'len', it shall still only return the amount of data indicated in 'len', discarding the remain.</XHTMLElement>
507 </DocElement>
508 <DocElement>
509 <XHTMLElement Type="LIST_ITEM">If the count element of parameter 'data_info' is set to NON-ZERO and its element 'data' is not set to ZERO, then the driver shall send the data stored in element 'data' up to the number given by the count element to the card. In case of protocol T=0 the count element is identical with parameter P3, in case of protocol T=1 it is identical with parameter Lc.</XHTMLElement>
510 </DocElement>
511 <DocElement>
512 <XHTMLElement Type="LIST_ITEM_END">If neither send nor receive data is given by the function parameters, then,. in case of protocol T=0, the function shall only send the command header to the card followed by parameter P3 set to ZERO. In case of protocol T=1 only the header is sent.</XHTMLElement>
513 </DocElement>
514 </Description>
515 <FuncDef IsLinkTarget="NO">
516 <Name>xch_apdu</Name>
517 <FuncUsage>
518 <Caller>SIM</Caller>
519 <Callee>DRIVER</Callee>
520 </FuncUsage>
521 </FuncDef>
522 <FuncRet>
523 <ItemLink>
524 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
525 <Name>sw1_2</Name>
526 </ItemLink>
527 <Comment>Status word</Comment>
528 </FuncRet>
529 <FuncArg>
530 <ItemLink>
531 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
532 <Name>reader_id</Name>
533 </ItemLink>
534 <Comment>Reader Id</Comment>
535 </FuncArg>
536 <FuncArg>
537 <ItemLink>
538 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
539 <Name>cmd_header</Name>
540 </ItemLink>
541 <Comment>Transparent command header</Comment>
542 </FuncArg>
543 <FuncArg>
544 <ItemLink>
545 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
546 <Name>data_info</Name>
547 </ItemLink>
548 <Comment>Send Data Buffer</Comment>
549 </FuncArg>
550 <FuncArg>
551 <ItemLink>
552 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
553 <Name>result_info</Name>
554 </ItemLink>
555 <Control>PTR</Control>
556 <Comment>Result Buffer</Comment>
557 </FuncArg>
558 <History>
559 <Date Day="30" Month="10" Year="2003"/>
560 <Author>FK</Author>
561 <Comment>Initial.</Comment>
562 </History>
563 <History>
564 <Date Day="3" Month="5" Year="2004"/>
565 <Author>FDU</Author>
566 <Comment>function renamed, parameters aligned to review report</Comment>
567 </History>
568 <History>
569 <Date Day="10" Month="6" Year="2004"/>
570 <Author>FDU</Author>
571 <Comment>reader id added</Comment>
572 </History>
573 </Function>
574 <Function>
575 <Description>
576 <DocElement>
577 <XHTMLElement Type="TEXT_SECTION">The function is used to establish communication between the PS and the SIM reader driver. Two call back function pointers are passed to the driver. There is no return value.</XHTMLElement>
578 </DocElement>
579 <DocElement>
580 <XHTMLElement Type="TEXT_SECTION">The call back to 'insert()' is executed by the driver, when it, being called by the function 'simdrv_reset()', is able to successfully reset the SIM card.</XHTMLElement>
581 </DocElement>
582 <DocElement>
583 <XHTMLElement Type="TEXT_SECTION">The call back 'remove()' is executed by the driver at any time during a card session, when it detects that the SIM card cannot be accessed any more.</XHTMLElement>
584 </DocElement>
585 </Description>
586 <FuncDef IsLinkTarget="NO">
587 <Name>register</Name>
588 <FuncUsage>
589 <Caller>SIM</Caller>
590 <Callee>DRIVER</Callee>
591 </FuncUsage>
592 </FuncDef>
593 <FuncArg>
594 <ItemLink>
595 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
596 <Name>insert</Name>
597 </ItemLink>
598 <Alias>insert</Alias>
599 <Control>PTR</Control>
600 <Comment>Function argument</Comment>
601 </FuncArg>
602 <FuncArg>
603 <ItemLink>
604 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
605 <Name>remove</Name>
606 </ItemLink>
607 <Alias>remove</Alias>
608 <Control>PTR</Control>
609 <Comment>Function argument</Comment>
610 </FuncArg>
611 <History>
612 <Date Day="20" Month="2" Year="2002"/>
613 <Author>FDU</Author>
614 <Comment>Initial.</Comment>
615 </History>
616 <History>
617 <Date Day="20" Month="11" Year="2003"/>
618 <Author>FK</Author>
619 <Comment>Parameters for callbacks added.</Comment>
620 </History>
621 <History>
622 <Date Day="3" Month="5" Year="2004"/>
623 <Author>FDU</Author>
624 <Comment>function renamed, parameters aligned to review report</Comment>
625 </History>
626 <History>
627 <Date Day="10" Month="6" Year="2004"/>
628 <Author>FDU</Author>
629 <Comment>config_request parameters added.</Comment>
630 </History>
631 <History>
632 <Date Day="19" Month="8" Year="2004"/>
633 <Author>FDU</Author>
634 <Comment>(void) added to remove pointer.</Comment>
635 </History>
636 </Function>
637 <Function>
638 <Description>
639 <DocElement>
640 <DocLink DocType="OTHER">
641 <Name/>
642 </DocLink>
643 </DocElement>
644 </Description>
645 <FuncDef IsLinkTarget="NO">
646 <Name>insert</Name>
647 <FuncUsage>
648 <Caller>SIM</Caller>
649 <Callee>DRIVER</Callee>
650 </FuncUsage>
651 </FuncDef>
652 <FuncArg>
653 <ItemLink>
654 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
655 <Name>atr_string_info</Name>
656 </ItemLink>
657 <Control>PTR</Control>
658 <Comment>Function argument</Comment>
659 </FuncArg>
660 <FuncArg>
661 <ItemLink>
662 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
663 <Name>config_requested</Name>
664 </ItemLink>
665 <Comment>Function argument</Comment>
666 </FuncArg>
667 <FuncArg>
668 <ItemLink>
669 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
670 <Name>config_characteristics</Name>
671 </ItemLink>
672 <Control>PTR</Control>
673 <Comment>Function argument</Comment>
674 </FuncArg>
675 <History>
676 <Date Day="28" Month="02" Year="2005"/>
677 <Author>JEJ</Author>
678 <Comment>Initial - Used to make function pointer as argument in simdrv_register function </Comment>
679 </History>
680 </Function>
681 <Function>
682 <Description>
683 <DocElement>
684 <DocLink DocType="OTHER">
685 <Name/>
686 </DocLink>
687 </DocElement>
688 </Description>
689 <FuncDef IsLinkTarget="NO">
690 <Name>remove</Name>
691 <FuncUsage>
692 <Caller>SIM</Caller>
693 <Callee>DRIVER</Callee>
694 </FuncUsage>
695 </FuncDef>
696 <History>
697 <Date Day="28" Month="02" Year="2005"/>
698 <Author/>
699 <Comment>Initial</Comment>
700 </History>
701 </Function>
702 </FunctionsSection>
703 <PrimStructElementsSection>
704 <Description>
705 <DocElement>
706 <XHTMLElement Type="TEXT_SECTION">This section contains all structured elements that are defined for the 8010_136_SIMDRV_SAP SAP</XHTMLElement>
707 </DocElement>
708 </Description>
709 <PrimStructElem>
710 <Description>
711 <DocElement>
712 <XHTMLElement Type="TEXT_SECTION">Contains the result of the ATR procedure, which the SIM hardware driver initiates during its start up sequence.</XHTMLElement>
713 </DocElement>
714 </Description>
715 <PrimStructElemDef Type="STRUCT">
716 <Name>atr_string_info</Name>
717 <Group>uicc</Group>
718 <Comment>SIM Card Info</Comment>
719 </PrimStructElemDef>
720 <PrimStructElemItem Presentation="MANDATORY">
721 <ItemLink>
722 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
723 <Name>atr_string</Name>
724 </ItemLink>
725 <Control>[2..SIZE_ATR_INFO]</Control>
726 <Comment>SIM Card Answer to reset string</Comment>
727 </PrimStructElemItem>
728 <History>
729 <Date Day="20" Month="2" Year="2002"/>
730 <Author>FDU</Author>
731 <Comment>Initial</Comment>
732 </History>
733 <History>
734 <Date Day="16" Month="12" Year="2002"/>
735 <Author>FDU</Author>
736 <Comment>Structure changed for element to a struct including a length byte</Comment>
737 </History>
738 <History>
739 <Date Day="3" Month="5" Year="2004"/>
740 <Author>FDU</Author>
741 <Comment>function renamed, parameters aligned to review report</Comment>
742 </History>
743 </PrimStructElem>
744 <PrimStructElem>
745 <Description>
746 <DocElement>
747 <XHTMLElement Type="TEXT_SECTION">The SIM driver uses this to return the response data retrieved when issuing a command.</XHTMLElement>
748 </DocElement>
749 </Description>
750 <PrimStructElemDef Type="STRUCT">
751 <Name>result_info</Name>
752 <Group>uicc</Group>
753 <Comment>Result Buffer</Comment>
754 </PrimStructElemDef>
755 <PrimStructElemItem Presentation="MANDATORY">
756 <ItemLink>
757 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
758 <Name>len</Name>
759 </ItemLink>
760 <Comment>Length of expected data</Comment>
761 </PrimStructElemItem>
762 <PrimStructElemItem Presentation="MANDATORY">
763 <ItemLink>
764 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
765 <Name>result</Name>
766 </ItemLink>
767 <Control>DYN[MIN_RESULT..MAX_RESULT]</Control>
768 <Comment>Result byte</Comment>
769 </PrimStructElemItem>
770 <History>
771 <Date Day="20" Month="2" Year="2002"/>
772 <Author>FDU</Author>
773 <Comment>Initial</Comment>
774 </History>
775 <History>
776 <Date Day="16" Month="12" Year="2002"/>
777 <Author>FDU</Author>
778 <Comment>Structure changed for element to a struct including a length byte</Comment>
779 </History>
780 <History>
781 <Date Day="3" Month="5" Year="2004"/>
782 <Author>FDU</Author>
783 <Comment>function renamed, parameters aligned to review report</Comment>
784 </History>
785 </PrimStructElem>
786 <PrimStructElem>
787 <Description>
788 <DocElement>
789 <XHTMLElement Type="TEXT_SECTION">The Update data element is used by the PS to transfer the data which it wants to update to the SIM hardware driver.</XHTMLElement>
790 </DocElement>
791 </Description>
792 <PrimStructElemDef Type="STRUCT">
793 <Name>data_info</Name>
794 <Group>uicc</Group>
795 <Comment>Data element info</Comment>
796 </PrimStructElemDef>
797 <PrimStructElemItem Presentation="MANDATORY">
798 <ItemLink>
799 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
800 <Name>data</Name>
801 </ItemLink>
802 <Control>DYN[MIN_DATA_SIZE..MAX_DATA_SIZE]</Control>
803 <Comment>Data element</Comment>
804 </PrimStructElemItem>
805 <History>
806 <Date Day="20" Month="2" Year="2002"/>
807 <Author>FDU</Author>
808 <Comment>Initial</Comment>
809 </History>
810 <History>
811 <Date Day="16" Month="12" Year="2002"/>
812 <Author>FDU</Author>
813 <Comment>Structure changed for element to a struct including a length byte</Comment>
814 </History>
815 <History>
816 <Date Day="3" Month="5" Year="2004"/>
817 <Author>FDU</Author>
818 <Comment>function renamed, parameters aligned to review report</Comment>
819 </History>
820 </PrimStructElem>
821 <PrimStructElem>
822 <Description>
823 <DocElement>
824 <XHTMLElement Type="TEXT_SECTION">A struct pointer to create a command header for sending transparent commands to the UICC</XHTMLElement>
825 </DocElement>
826 </Description>
827 <PrimStructElemDef Type="STRUCT">
828 <Name>cmd_header</Name>
829 <Group>uicc</Group>
830 <Comment>Transparent command header</Comment>
831 </PrimStructElemDef>
832 <PrimStructElemItem Presentation="MANDATORY">
833 <ItemLink>
834 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
835 <Name>cla</Name>
836 </ItemLink>
837 <Comment>Class Byte value</Comment>
838 </PrimStructElemItem>
839 <PrimStructElemItem Presentation="MANDATORY">
840 <ItemLink>
841 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
842 <Name>ins</Name>
843 </ItemLink>
844 <Comment>Instruction Code</Comment>
845 </PrimStructElemItem>
846 <PrimStructElemItem Presentation="MANDATORY">
847 <ItemLink>
848 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
849 <Name>p1</Name>
850 </ItemLink>
851 <Comment>Parameter P1</Comment>
852 </PrimStructElemItem>
853 <PrimStructElemItem Presentation="MANDATORY">
854 <ItemLink>
855 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
856 <Name>p2</Name>
857 </ItemLink>
858 <Comment>Parameter P2</Comment>
859 </PrimStructElemItem>
860 <History>
861 <Date Day="30" Month="10" Year="2003"/>
862 <Author>FK</Author>
863 <Comment>Initial</Comment>
864 </History>
865 </PrimStructElem>
866 <PrimStructElem>
867 <Description>
868 <DocElement>
869 <XHTMLElement Type="TEXT_SECTION">The PS shall deliver the configuration characteristics coded according to [ETSI 102 221, 11.1.1.4.6.1].</XHTMLElement>
870 </DocElement>
871 </Description>
872 <PrimStructElemDef Type="STRUCT">
873 <Name>config_characteristics</Name>
874 <Group>uicc</Group>
875 <Comment>Configuration Characteristics</Comment>
876 </PrimStructElemDef>
877 <PrimStructElemItem Presentation="MANDATORY">
878 <ItemLink>
879 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
880 <Name>uicc_characteristics</Name>
881 </ItemLink>
882 <Comment>UICC Characteristics</Comment>
883 </PrimStructElemItem>
884 <History>
885 <Date Day="10" Month="6" Year="2004"/>
886 <Author>FDU</Author>
887 <Comment>function renamed, parameters aligned to review report</Comment>
888 </History>
889 </PrimStructElem>
890 </PrimStructElementsSection>
891 <PrimBasicElementsSection>
892 <Description>
893 <DocElement>
894 <XHTMLElement Type="TEXT_SECTION">This section contains all basic elements that are defined for the 8010_136_SIMDRV_SAP SAP</XHTMLElement>
895 </DocElement>
896 </Description>
897 <PrimBasicElem>
898 <Description>
899 <DocElement>
900 <XHTMLElement Type="TEXT_SECTION">The insert call back function to which the pointer refers shall be executed by the driver after the PS has executed the simdrv_reset() command call, if and only if the activation of the inserted UICC was successful. It has a two parameters. One used to indicate to the PS whether UICC configuration characteristics are required by the driver and one which points to a structure, where the PS can store the retrieved configuration characteristics. (See chapter 6)</XHTMLElement>
901 </DocElement>
902 </Description>
903 <PrimBasicElemDef>
904 <Name>insert_ptr</Name>
905 <Type>U32</Type>
906 <Group>uicc</Group>
907 <Comment>insert pointer</Comment>
908 </PrimBasicElemDef>
909 <History>
910 <Date Day="21" Month="2" Year="2002"/>
911 <Author>FDU</Author>
912 <Comment>Initial</Comment>
913 </History>
914 <History>
915 <Date Day="3" Month="5" Year="2004"/>
916 <Author>FDU</Author>
917 <Comment>function renamed, parameters aligned to review report</Comment>
918 </History>
919 </PrimBasicElem>
920 <PrimBasicElem>
921 <Description>
922 <DocElement>
923 <XHTMLElement Type="TEXT_SECTION">The remove call back function to which the pointer refers, shall be executed by the driver when the driver detects that the inserted UICC has been removed. Either this detection is due to missing reply to command or due to hardware removal detection.</XHTMLElement>
924 </DocElement>
925 </Description>
926 <PrimBasicElemDef>
927 <Name>remove_ptr</Name>
928 <Type>U32</Type>
929 <Group>uicc</Group>
930 <Comment>remove pointer</Comment>
931 </PrimBasicElemDef>
932 <History>
933 <Date Day="12" Month="12" Year="1954"/>
934 <Author>doc2xml</Author>
935 <Comment>no history in source document</Comment>
936 </History>
937 </PrimBasicElem>
938 <PrimBasicElem>
939 <Description>
940 <DocElement>
941 <XHTMLElement Type="TEXT_SECTION">Contains the result of the ATR procedure, which the SIM hardware driver initiates during its start up sequence.</XHTMLElement>
942 </DocElement>
943 </Description>
944 <PrimBasicElemDef>
945 <Name>atr_string</Name>
946 <Type>U8</Type>
947 <Group>uicc</Group>
948 <Comment>SIM Card Answer to reset string</Comment>
949 </PrimBasicElemDef>
950 <History>
951 <Date Day="20" Month="2" Year="2002"/>
952 <Author>FDU</Author>
953 <Comment>Initial</Comment>
954 </History>
955 <History>
956 <Date Day="16" Month="12" Year="2002"/>
957 <Author>FDU</Author>
958 <Comment>Structure changed for element to a struct including a length byte</Comment>
959 </History>
960 <History>
961 <Date Day="3" Month="5" Year="2004"/>
962 <Author>FDU</Author>
963 <Comment>function renamed, parameters aligned to review report</Comment>
964 </History>
965 </PrimBasicElem>
966 <PrimBasicElem>
967 <Description>
968 <DocElement>
969 <XHTMLElement Type="TEXT_SECTION">The return value is used by the SIM hardware driver to indicate to the PS whether a card is inserted or not and if it is fully functioning.</XHTMLElement>
970 </DocElement>
971 </Description>
972 <PrimBasicElemDef>
973 <Name>reset_return_val</Name>
974 <Type>U8</Type>
975 <Group>uicc</Group>
976 <Comment>Reset return value</Comment>
977 </PrimBasicElemDef>
978 <ValuesLink>
979 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
980 <Name>VAL_reset_return_val</Name>
981 </ValuesLink>
982 <History>
983 <Date Day="20" Month="2" Year="2002"/>
984 <Author>FDU</Author>
985 <Comment>Initial</Comment>
986 </History>
987 <History>
988 <Date Day="5" Month="7" Year="2002"/>
989 <Author>FDU</Author>
990 <Comment>Meaning of byte changed</Comment>
991 </History>
992 <History>
993 <Date Day="3" Month="5" Year="2004"/>
994 <Author>FDU</Author>
995 <Comment>function renamed, parameters aligned to review report</Comment>
996 </History>
997 <History>
998 <Date Day="28" Month="6" Year="2004"/>
999 <Author>FDU</Author>
1000 <Comment>Added latter two return values after desk check.</Comment>
1001 </History>
1002 </PrimBasicElem>
1003 <PrimBasicElem>
1004 <Description>
1005 <DocElement>
1006 <XHTMLElement Type="TEXT_SECTION">The SIM driver uses this to return the response data retrieved when issuing a command.</XHTMLElement>
1007 </DocElement>
1008 </Description>
1009 <PrimBasicElemDef>
1010 <Name>result</Name>
1011 <Type>U8</Type>
1012 <Group>uicc</Group>
1013 <Comment>Result byte</Comment>
1014 </PrimBasicElemDef>
1015 <History>
1016 <Date Day="20" Month="2" Year="2002"/>
1017 <Author>FDU</Author>
1018 <Comment>Initial</Comment>
1019 </History>
1020 <History>
1021 <Date Day="16" Month="12" Year="2002"/>
1022 <Author>FDU</Author>
1023 <Comment>Structure changed for element to a struct including a length byte</Comment>
1024 </History>
1025 <History>
1026 <Date Day="3" Month="5" Year="2004"/>
1027 <Author>FDU</Author>
1028 <Comment>function renamed, parameters aligned to review report</Comment>
1029 </History>
1030 </PrimBasicElem>
1031 <PrimBasicElem>
1032 <Description>
1033 <DocElement>
1034 <XHTMLElement Type="TEXT_SECTION">Used to indicate maximum length, in bytes, of data which the ME expects the UICC to return, e.g. during a READ_RECORD or a READ_BINARY command. In cases where the size of the return data is undeterminable, the value shall be LENGTH_UNKNOWN (See chapter 6)</XHTMLElement>
1035 </DocElement>
1036 </Description>
1037 <PrimBasicElemDef>
1038 <Name>len</Name>
1039 <Type>U16</Type>
1040 <Group>uicc</Group>
1041 <Comment>Maximum length of expected data</Comment>
1042 </PrimBasicElemDef>
1043 <ValuesLink>
1044 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
1045 <Name>VAL_len</Name>
1046 </ValuesLink>
1047 <History>
1048 <Date Day="21" Month="2" Year="2002"/>
1049 <Author>FDU</Author>
1050 <Comment>Initial</Comment>
1051 </History>
1052 <History>
1053 <Date Day="3" Month="5" Year="2004"/>
1054 <Author>FDU</Author>
1055 <Comment>function renamed, parameters aligned to review report</Comment>
1056 </History>
1057 </PrimBasicElem>
1058 <PrimBasicElem>
1059 <Description>
1060 <DocElement>
1061 <XHTMLElement Type="TEXT_SECTION">The Update data element is used by the PS to transfer the data which it wants to update to the SIM hardware driver.</XHTMLElement>
1062 </DocElement>
1063 </Description>
1064 <PrimBasicElemDef>
1065 <Name>data</Name>
1066 <Type>U8</Type>
1067 <Group>uicc</Group>
1068 <Comment>Data element</Comment>
1069 </PrimBasicElemDef>
1070 <History>
1071 <Date Day="20" Month="2" Year="2002"/>
1072 <Author>FDU</Author>
1073 <Comment>Initial</Comment>
1074 </History>
1075 <History>
1076 <Date Day="16" Month="12" Year="2002"/>
1077 <Author>FDU</Author>
1078 <Comment>Structure changed for element to a struct including a length byte</Comment>
1079 </History>
1080 <History>
1081 <Date Day="3" Month="5" Year="2004"/>
1082 <Author>FDU</Author>
1083 <Comment>function renamed, parameters aligned to review report</Comment>
1084 </History>
1085 </PrimBasicElem>
1086 <PrimBasicElem>
1087 <Description>
1088 <DocElement>
1089 <XHTMLElement Type="TEXT_SECTION">After each command issued by the ME to the UICC, the SIM hardware driver shall return the two status bytes from the UICC. The PS interprets these value and acts upon them on its own. The possible values of the status word can be found in [GSM 11.11] and [ETSI TS 102 221]. They are returned in a U16, SW1 occupies bits 8..15 and SW2 occupies bits 0..7 of the value.</XHTMLElement>
1090 </DocElement>
1091 <DocElement>
1092 <XHTMLElement Type="TEXT_SECTION">Additionally there are a couple of driver error codes which are returned in case of unrecoverable communication problems between ME and UICC. Before the driver returns any of these error codes, it shall retry the causing operation at least once.</XHTMLElement>
1093 </DocElement>
1094 </Description>
1095 <PrimBasicElemDef>
1096 <Name>sw1_2</Name>
1097 <Type>U16</Type>
1098 <Group>uicc</Group>
1099 <Comment>Status Words</Comment>
1100 </PrimBasicElemDef>
1101 <ValuesLink>
1102 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
1103 <Name>VAL_sw1_2</Name>
1104 </ValuesLink>
1105 <History>
1106 <Date Day="21" Month="2" Year="2002"/>
1107 <Author>FDU</Author>
1108 <Comment>Initial</Comment>
1109 </History>
1110 <History>
1111 <Date Day="8" Month="12" Year="2003"/>
1112 <Author>FK</Author>
1113 <Comment>Revised</Comment>
1114 </History>
1115 <History>
1116 <Date Day="3" Month="5" Year="2004"/>
1117 <Author>FDU</Author>
1118 <Comment>function renamed, parameters aligned to review report</Comment>
1119 </History>
1120 </PrimBasicElem>
1121 <PrimBasicElem>
1122 <Description>
1123 <DocElement>
1124 <XHTMLElement Type="TEXT_SECTION">When communicating with an UMTS Application, the Class Byte shall be set according to [ETSI 102 221, 10.1.2], either code 0x00 (standard ISO 7816-4 Class Byte) or code 0x80 (for additional instructions defined in ETSI 102 221) dependent on the type of the selected command. For a GSM application according to GSM 11.11 / 3GPP 51.011 the code 0xA0 is used for all instructions.</XHTMLElement>
1125 </DocElement>
1126 </Description>
1127 <PrimBasicElemDef>
1128 <Name>cla</Name>
1129 <Type>U8</Type>
1130 <Group>uicc</Group>
1131 <Comment>Class Byte</Comment>
1132 </PrimBasicElemDef>
1133 <ValuesLink>
1134 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
1135 <Name>VAL_cla</Name>
1136 </ValuesLink>
1137 <History>
1138 <Date Day="4" Month="7" Year="2002"/>
1139 <Author>FDU</Author>
1140 <Comment>Initial</Comment>
1141 </History>
1142 <History>
1143 <Date Day="5" Month="12" Year="2003"/>
1144 <Author>FK</Author>
1145 <Comment>Revised</Comment>
1146 </History>
1147 <History>
1148 <Date Day="3" Month="5" Year="2004"/>
1149 <Author>FDU</Author>
1150 <Comment>function renamed, parameters aligned to review report</Comment>
1151 </History>
1152 </PrimBasicElem>
1153 <PrimBasicElem>
1154 <Description>
1155 <DocElement>
1156 <XHTMLElement Type="TEXT_SECTION">The parameter defines the SIM instruction code for SIM access.</XHTMLElement>
1157 </DocElement>
1158 </Description>
1159 <PrimBasicElemDef>
1160 <Name>ins</Name>
1161 <Type>U8</Type>
1162 <Group>uicc</Group>
1163 <Comment>instruction code</Comment>
1164 </PrimBasicElemDef>
1165 <ValuesLink>
1166 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
1167 <Name>VAL_ins</Name>
1168 </ValuesLink>
1169 <History>
1170 <Date Day="24" Month="4" Year="2002"/>
1171 <Author>JK</Author>
1172 <Comment>Initial</Comment>
1173 </History>
1174 <History>
1175 <Date Day="1" Month="5" Year="2003"/>
1176 <Author>KBS</Author>
1177 <Comment>SIM_ prefix removed due to autoprefixing</Comment>
1178 </History>
1179 <History>
1180 <Date Day="8" Month="12" Year="2003"/>
1181 <Author>FK</Author>
1182 <Comment>Incorporated from SAP SIM</Comment>
1183 </History>
1184 </PrimBasicElem>
1185 <PrimBasicElem>
1186 <Description>
1187 <DocElement>
1188 <XHTMLElement Type="TEXT_SECTION">Used to indicate to the SIM reader driver whether or not a voltage selection shall be performed or not. If set to REQ_VOLTAGE_SEL, the SIM reader driver does a regular reset of the card in which it performs the voltage selection procedure.</XHTMLElement>
1189 </DocElement>
1190 <DocElement>
1191 <XHTMLElement Type="TEXT_SECTION">If set to OMIT_VOLTAGE_SEL and the card has been activated with a simdrv_reset() call prior to this, thus having a used voltage already, it shall reset the card using only the currently used voltage. This also applies for <i>UICC Characteristics.</i></XHTMLElement>
1192 </DocElement>
1193 <DocElement>
1194 <XHTMLElement Type="TEXT_SECTION">This is a special case, where the SIM application toolkit requests a reset of the card, see [3G 11.14, 6.4.7]</XHTMLElement>
1195 </DocElement>
1196 </Description>
1197 <PrimBasicElemDef>
1198 <Name>voltage_select</Name>
1199 <Type>U8</Type>
1200 <Group>uicc</Group>
1201 <Comment>Perform Voltage Selection</Comment>
1202 </PrimBasicElemDef>
1203 <ValuesLink>
1204 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
1205 <Name>VAL_voltage_select</Name>
1206 </ValuesLink>
1207 <History>
1208 <Date Day="3" Month="5" Year="2004"/>
1209 <Author>FDU</Author>
1210 <Comment>Initial</Comment>
1211 </History>
1212 </PrimBasicElem>
1213 <PrimBasicElem>
1214 <Description>
1215 <DocElement>
1216 <XHTMLElement Type="TEXT_SECTION">The parameters P1 and P2 are individually coded in relevance to what type of command is to be performed. Coding according to [3G 11.11] and [ETSI 102 221]</XHTMLElement>
1217 </DocElement>
1218 </Description>
1219 <PrimBasicElemDef>
1220 <Name>p1</Name>
1221 <Type>U8</Type>
1222 <Group>uicc</Group>
1223 <Comment>Parameter 1 of the SIM APDU</Comment>
1224 </PrimBasicElemDef>
1225 <History>
1226 <Date Day="3" Month="5" Year="2004"/>
1227 <Author>FDU</Author>
1228 <Comment>function renamed, parameters aligned to review report</Comment>
1229 </History>
1230 </PrimBasicElem>
1231 <PrimBasicElem>
1232 <Description>
1233 <DocElement>
1234 <XHTMLElement Type="TEXT_SECTION">The parameters P1 and P2 are individually coded in relevance to what type of command is to be performed. Coding according to [3G 11.11] and [ETSI 102 221]</XHTMLElement>
1235 </DocElement>
1236 </Description>
1237 <PrimBasicElemDef>
1238 <Name>p2</Name>
1239 <Type>U8</Type>
1240 <Group>uicc</Group>
1241 <Comment>Parameter 2 of the SIM APDU</Comment>
1242 </PrimBasicElemDef>
1243 <History>
1244 <Date Day="3" Month="5" Year="2004"/>
1245 <Author>FDU</Author>
1246 <Comment>function renamed, parameters aligned to review report</Comment>
1247 </History>
1248 </PrimBasicElem>
1249 <PrimBasicElem>
1250 <Description>
1251 <DocElement>
1252 <XHTMLElement Type="TEXT_SECTION">This parameter is used by the driver to indicate that the PS must retrieve UICC characteristics from the MF ('3F00') and deliver them to the driver using the provided pointer reference (see chapter 5.15). This will occur in situations were the inserted cards does not deliver e.g. <i>preferred clock stop level</i> in the ATR. If the value of the parameter is SIMDRV_OMIT_CONFIG_CHARACTERISTICS, the PS must never try to access data using the provided pointer.</XHTMLElement>
1253 </DocElement>
1254 </Description>
1255 <PrimBasicElemDef>
1256 <Name>config_requested</Name>
1257 <Type>U8</Type>
1258 <Group>uicc</Group>
1259 <Comment>Configuration Characteristics requested</Comment>
1260 </PrimBasicElemDef>
1261 <ValuesLink>
1262 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
1263 <Name>VAL_config_requested</Name>
1264 </ValuesLink>
1265 <History>
1266 <Date Day="10" Month="6" Year="2004"/>
1267 <Author>FDU</Author>
1268 <Comment>function renamed, parameters aligned to review report</Comment>
1269 </History>
1270 </PrimBasicElem>
1271 <PrimBasicElem>
1272 <Description>
1273 <DocElement>
1274 <XHTMLElement Type="TEXT_SECTION">Used to indicate to the driver which reader the currently command is issued towards.</XHTMLElement>
1275 </DocElement>
1276 </Description>
1277 <PrimBasicElemDef>
1278 <Name>reader_id</Name>
1279 <Type>U8</Type>
1280 <Group>uicc</Group>
1281 <Comment>Reader Id</Comment>
1282 </PrimBasicElemDef>
1283 <ValuesLink>
1284 <DocName DocType="SAP">8010_136_simdrv_sap</DocName>
1285 <Name>VAL_reader_id</Name>
1286 </ValuesLink>
1287 <History>
1288 <Date Day="10" Month="6" Year="2004"/>
1289 <Author>FDU</Author>
1290 <Comment>function renamed, parameters aligned to review report</Comment>
1291 </History>
1292 </PrimBasicElem>
1293 <PrimBasicElem>
1294 <Description>
1295 <DocElement>
1296 <XHTMLElement Type="TEXT_SECTION">Used to deliver the UICC Characteristics of the MF to the driver</XHTMLElement>
1297 </DocElement>
1298 </Description>
1299 <PrimBasicElemDef>
1300 <Name>uicc_characteristics</Name>
1301 <Type>U8</Type>
1302 <Group>uicc</Group>
1303 <Comment>UICC Characteristics</Comment>
1304 </PrimBasicElemDef>
1305 <History>
1306 <Date Day="10" Month="6" Year="2004"/>
1307 <Author>FDU</Author>
1308 <Comment>function renamed, parameters aligned to review report</Comment>
1309 </History>
1310 </PrimBasicElem>
1311 </PrimBasicElementsSection>
1312 <ValuesSection>
1313 <Description>
1314 <DocElement>
1315 <XHTMLElement Type="TEXT_SECTION">This section contains all sets of values that are defined for the 8010_136_SIMDRV_SAP SAP</XHTMLElement>
1316 </DocElement>
1317 </Description>
1318 <Values>
1319 <Description>
1320 <DocElement>
1321 <XHTMLElement Type="TEXT_SECTION"/>
1322 </DocElement>
1323 </Description>
1324 <ValuesDef>
1325 <Name>VAL_reset_return_val</Name>
1326 <Group>uicc</Group>
1327 <Comment>values for reset_return_val</Comment>
1328 </ValuesDef>
1329 <ValuesItem>
1330 <Value ValueType="DEC">0</Value>
1331 <Alias>SIM_INSERTED</Alias>
1332 <Comment>A SIM is inserted and ATR/PPS was successful</Comment>
1333 </ValuesItem>
1334 <ValuesItem>
1335 <Value ValueType="DEC">1</Value>
1336 <Alias>SIM_NOT_INSERTED</Alias>
1337 <Comment>No SIM inserted (hardware detected)</Comment>
1338 </ValuesItem>
1339 <ValuesItem>
1340 <Value ValueType="DEC">2</Value>
1341 <Alias>INVALID_CARD</Alias>
1342 <Comment>Card is not responding or gives unintelligible answers, communications time out.</Comment>
1343 </ValuesItem>
1344 <ValuesItem>
1345 <Value ValueType="DEC">3</Value>
1346 <Alias>ME_FAILURE</Alias>
1347 <Comment>Power management related problems, e.g. voltage selection</Comment>
1348 </ValuesItem>
1349 <ValuesItem>
1350 <Value ValueType="DEC">4</Value>
1351 <Alias>IMPROPER_CALL_BACK</Alias>
1352 <Comment>simdrv_register function called with pointer improperly set, e.g. NULL.</Comment>
1353 </ValuesItem>
1354 <ValuesItem>
1355 <Value ValueType="DEC">5</Value>
1356 <Alias>ME_READER_NOT_AVAILABLE</Alias>
1357 <Comment>The reader requested is not available</Comment>
1358 </ValuesItem>
1359 <History>
1360 <Date Day="16" Month="2" Year="2005"/>
1361 <Author>doc2XML</Author>
1362 <Comment>Initial</Comment>
1363 </History>
1364 </Values>
1365 <Values>
1366 <Description>
1367 <DocElement>
1368 <XHTMLElement Type="TEXT_SECTION"/>
1369 </DocElement>
1370 </Description>
1371 <ValuesDef>
1372 <Name>VAL_len</Name>
1373 <Group>uicc</Group>
1374 <Comment>values for len</Comment>
1375 </ValuesDef>
1376 <ValuesItem>
1377 <Value ValueType="HEX">FFFF</Value>
1378 <Alias>LENGTH_UNKNOWN</Alias>
1379 <Comment>Indicating that the length expected is unknown.</Comment>
1380 </ValuesItem>
1381 <ValuesRange ValueType="HEX">
1382 <MinValue>00</MinValue>
1383 <MaxValue>100</MaxValue>
1384 <Comment>Range of Length of Data</Comment>
1385 </ValuesRange>
1386 <History>
1387 <Date Day="16" Month="2" Year="2005"/>
1388 <Author>doc2XML</Author>
1389 <Comment>Initial</Comment>
1390 </History>
1391 </Values>
1392 <Values>
1393 <Description>
1394 <DocElement>
1395 <XHTMLElement Type="TEXT_SECTION"/>
1396 </DocElement>
1397 </Description>
1398 <ValuesDef>
1399 <Name>VAL_sw1_2</Name>
1400 <Group>uicc</Group>
1401 <Comment>values for sw1_2</Comment>
1402 </ValuesDef>
1403 <ValuesItem>
1404 <Value ValueType="HEX">0001</Value>
1405 <Alias>ERR_NOCARD</Alias>
1406 <Comment>No SIM inserted (hardware detected)</Comment>
1407 </ValuesItem>
1408 <ValuesItem>
1409 <Value ValueType="HEX">0002</Value>
1410 <Alias>ERR_NOT_RESET</Alias>
1411 <Comment>A reset has not been performed on the driver with the requested Id.</Comment>
1412 </ValuesItem>
1413 <ValuesItem>
1414 <Value ValueType="HEX">0003</Value>
1415 <Alias>ERR_ME_FAIL</Alias>
1416 <Comment>Unrecoverable ME failure (for instance interrupt fails to occur)</Comment>
1417 </ValuesItem>
1418 <ValuesItem>
1419 <Value ValueType="HEX">0004</Value>
1420 <Alias>ERR_RETRY_FAIL</Alias>
1421 <Comment>ME/SIM communication failed after certain retries, SIM reset required</Comment>
1422 </ValuesItem>
1423 <ValuesItem>
1424 <Value ValueType="HEX">0005</Value>
1425 <Alias>ERR_PARAM_WRONG</Alias>
1426 <Comment>A driver function is called with invalid parameters</Comment>
1427 </ValuesItem>
1428 <History>
1429 <Date Day="16" Month="2" Year="2005"/>
1430 <Author>doc2XML</Author>
1431 <Comment>Initial</Comment>
1432 </History>
1433 </Values>
1434 <Values>
1435 <Description>
1436 <DocElement>
1437 <XHTMLElement Type="TEXT_SECTION"/>
1438 </DocElement>
1439 </Description>
1440 <ValuesDef>
1441 <Name>VAL_cla</Name>
1442 <Group>uicc</Group>
1443 <Comment>values for cla</Comment>
1444 </ValuesDef>
1445 <ValuesItem>
1446 <Value ValueType="HEX">A0</Value>
1447 <Alias>GSM_CLASS_BYTE</Alias>
1448 <Comment>GSM Class byte according to [GSM 11.11 / 3GPP 51.011]</Comment>
1449 </ValuesItem>
1450 <ValuesItem>
1451 <Value ValueType="HEX">80</Value>
1452 <Alias>UMTS_CLASS_BYTE</Alias>
1453 <Comment>UMTS Class byte according to [ETSI 102 221 10.1.2]</Comment>
1454 </ValuesItem>
1455 <ValuesItem>
1456 <Value ValueType="HEX">00</Value>
1457 <Alias>UICC_CLASS_BYTE</Alias>
1458 <Comment>UICC Class byte according to [ISO 7816-4]</Comment>
1459 </ValuesItem>
1460 <History>
1461 <Date Day="16" Month="2" Year="2005"/>
1462 <Author>doc2XML</Author>
1463 <Comment>Initial</Comment>
1464 </History>
1465 </Values>
1466 <Values>
1467 <Description>
1468 <DocElement>
1469 <XHTMLElement Type="TEXT_SECTION"/>
1470 </DocElement>
1471 </Description>
1472 <ValuesDef>
1473 <Name>VAL_ins</Name>
1474 <Group>uicc</Group>
1475 <Comment>values for ins</Comment>
1476 </ValuesDef>
1477 <ValuesItem>
1478 <Value ValueType="HEX">A4</Value>
1479 <Alias>INS_SELECT</Alias>
1480 <Comment>Select Instruction</Comment>
1481 </ValuesItem>
1482 <ValuesItem>
1483 <Value ValueType="HEX">F2</Value>
1484 <Alias>INS_STATUS</Alias>
1485 <Comment>Status Instruction</Comment>
1486 </ValuesItem>
1487 <ValuesItem>
1488 <Value ValueType="HEX">B0</Value>
1489 <Alias>INS_READ_BINARY</Alias>
1490 <Comment>Read Binary Instruction</Comment>
1491 </ValuesItem>
1492 <ValuesItem>
1493 <Value ValueType="HEX">D6</Value>
1494 <Alias>INS_UPDATE_BINARY</Alias>
1495 <Comment>Update Binary Instruction</Comment>
1496 </ValuesItem>
1497 <ValuesItem>
1498 <Value ValueType="HEX">B2</Value>
1499 <Alias>INS_READ_RECORD</Alias>
1500 <Comment>Read Record Instruction</Comment>
1501 </ValuesItem>
1502 <ValuesItem>
1503 <Value ValueType="HEX">DC</Value>
1504 <Alias>INS_UPDATE_RECORD</Alias>
1505 <Comment>Update Record Instruction</Comment>
1506 </ValuesItem>
1507 <ValuesItem>
1508 <Value ValueType="HEX">A2</Value>
1509 <Alias>INS_SEEK</Alias>
1510 <Comment>Seek Instruction</Comment>
1511 </ValuesItem>
1512 <ValuesItem>
1513 <Value ValueType="HEX">32</Value>
1514 <Alias>INS_INCREASE</Alias>
1515 <Comment>Increase Instruction</Comment>
1516 </ValuesItem>
1517 <ValuesItem>
1518 <Value ValueType="HEX">20</Value>
1519 <Alias>INS_VERIFY_CHV</Alias>
1520 <Comment>Verify Chv Instruction</Comment>
1521 </ValuesItem>
1522 <ValuesItem>
1523 <Value ValueType="HEX">24</Value>
1524 <Alias>INS_CHANGE_CHV</Alias>
1525 <Comment>Change Chv Instruction</Comment>
1526 </ValuesItem>
1527 <ValuesItem>
1528 <Value ValueType="HEX">26</Value>
1529 <Alias>INS_DISABLE_CHV</Alias>
1530 <Comment>Disable Chv Instruction</Comment>
1531 </ValuesItem>
1532 <ValuesItem>
1533 <Value ValueType="HEX">28</Value>
1534 <Alias>INS_ENABLE_CHV</Alias>
1535 <Comment>Ensable Chv Instruction</Comment>
1536 </ValuesItem>
1537 <ValuesItem>
1538 <Value ValueType="HEX">2C</Value>
1539 <Alias>INS_UNBLOCK_CHV</Alias>
1540 <Comment>Unblock Chv Instruction</Comment>
1541 </ValuesItem>
1542 <ValuesItem>
1543 <Value ValueType="HEX">04</Value>
1544 <Alias>INS_INVALIDATE</Alias>
1545 <Comment>Invalidate Instruction</Comment>
1546 </ValuesItem>
1547 <ValuesItem>
1548 <Value ValueType="HEX">44</Value>
1549 <Alias>INS_REHABILITATE</Alias>
1550 <Comment>Rehabilitate Instruction</Comment>
1551 </ValuesItem>
1552 <ValuesItem>
1553 <Value ValueType="HEX">88</Value>
1554 <Alias>INS_AUTHENTICATE</Alias>
1555 <Comment>Run GSM Algorithm (2/2.5G) / Authenticate (3G) Instruction</Comment>
1556 </ValuesItem>
1557 <ValuesItem>
1558 <Value ValueType="HEX">10</Value>
1559 <Alias>INS_TERMINAL_PROFILE</Alias>
1560 <Comment>Terminal Profile Instruction</Comment>
1561 </ValuesItem>
1562 <ValuesItem>
1563 <Value ValueType="HEX">C2</Value>
1564 <Alias>INS_ENVELOPE</Alias>
1565 <Comment>Envelope Instruction</Comment>
1566 </ValuesItem>
1567 <ValuesItem>
1568 <Value ValueType="HEX">12</Value>
1569 <Alias>INS_FETCH</Alias>
1570 <Comment>Fetch Instruction</Comment>
1571 </ValuesItem>
1572 <ValuesItem>
1573 <Value ValueType="HEX">14</Value>
1574 <Alias>INS_TERMINAL_RESPONSE</Alias>
1575 <Comment>Terminal Response Instruction</Comment>
1576 </ValuesItem>
1577 <ValuesItem>
1578 <Value ValueType="HEX">C0</Value>
1579 <Alias>INS_GET_RESPONSE</Alias>
1580 <Comment>Get Response Instruction</Comment>
1581 </ValuesItem>
1582 <History>
1583 <Date Day="16" Month="2" Year="2005"/>
1584 <Author>doc2XML</Author>
1585 <Comment>Initial</Comment>
1586 </History>
1587 </Values>
1588 <Values>
1589 <Description>
1590 <DocElement>
1591 <XHTMLElement Type="TEXT_SECTION"/>
1592 </DocElement>
1593 </Description>
1594 <ValuesDef>
1595 <Name>VAL_voltage_select</Name>
1596 <Group>uicc</Group>
1597 <Comment>values for voltage_select</Comment>
1598 </ValuesDef>
1599 <ValuesItem>
1600 <Value ValueType="DEC">0</Value>
1601 <Alias>REQ_VOLTAGE_SEL</Alias>
1602 <Comment>The SIM reader driver shall perform voltage selection</Comment>
1603 </ValuesItem>
1604 <ValuesItem>
1605 <Value ValueType="DEC">1</Value>
1606 <Alias>OMIT_VOLTAGE_SEL</Alias>
1607 <Comment>The SIM reader driver shall restart with the current voltage</Comment>
1608 </ValuesItem>
1609 <History>
1610 <Date Day="16" Month="2" Year="2005"/>
1611 <Author>doc2XML</Author>
1612 <Comment>Initial</Comment>
1613 </History>
1614 </Values>
1615 <Values>
1616 <Description>
1617 <DocElement>
1618 <XHTMLElement Type="TEXT_SECTION"/>
1619 </DocElement>
1620 </Description>
1621 <ValuesDef>
1622 <Name>VAL_config_requested</Name>
1623 <Group>uicc</Group>
1624 <Comment>values for config_requested</Comment>
1625 </ValuesDef>
1626 <ValuesItem>
1627 <Value ValueType="HEX">00</Value>
1628 <Alias>OMIT_CONFIG_CHARACTERISTICS</Alias>
1629 <Comment>PS Shall not retrieve Configuration Characteristics</Comment>
1630 </ValuesItem>
1631 <ValuesItem>
1632 <Value ValueType="HEX">01</Value>
1633 <Alias>REQUEST_CONFIG_CHARACTERISTICS</Alias>
1634 <Comment>PS Shall retrieve Configuration Characteristics</Comment>
1635 </ValuesItem>
1636 <History>
1637 <Date Day="16" Month="2" Year="2005"/>
1638 <Author>doc2XML</Author>
1639 <Comment>Initial</Comment>
1640 </History>
1641 </Values>
1642 <Values>
1643 <Description>
1644 <DocElement>
1645 <XHTMLElement Type="TEXT_SECTION"/>
1646 </DocElement>
1647 </Description>
1648 <ValuesDef>
1649 <Name>VAL_reader_id</Name>
1650 <Group>uicc</Group>
1651 <Comment>values for reader_id</Comment>
1652 </ValuesDef>
1653 <ValuesRange ValueType="ALPHA">
1654 <MinValue>01</MinValue>
1655 <MaxValue>MAX_READERS</MaxValue>
1656 <Comment>Range of Id's of readers</Comment>
1657 </ValuesRange>
1658 <History>
1659 <Date Day="16" Month="2" Year="2005"/>
1660 <Author>doc2XML</Author>
1661 <Comment>Initial</Comment>
1662 </History>
1663 </Values>
1664 </ValuesSection>
1665 </SAP>