7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept xml:lang="en" id="GUID-107AE89E-901E-535F-8D1A-EE347D7822B1"><title>Architecture</title><shortdesc>This topic describes the architecture of the Serial Communications Server. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p>The Serial Communications Server uses the Symbian OS client/server framework. Clients use <codeph>R</codeph> classes that send requests to the Serial Communications Server. The server in turn passes requests to an appropriate plug-in module that handles the particular communication protocol. These plug-in modules are known as <i>Serial Protocol Modules</i> or <i>CSYs</i>. The Serial Protocol Modules are loaded by the Serial Communications server, and are not directly accessed by client applications. A Symbian OS phone may include a number of Serial Protocol Modules as standard, such as for handling RS232 and infra-red serial communications. The Serial Protocol Module API allows new Serial Protocol Modules modules to be developed. </p> <p>The Serial Communications Server provides a publishedAll API to access the serial ports of the device. The Serial Communications Server provides functionality such as timeouts and port sharing for all Serial Protocol Modules. The Serial Protocol Modules provide the specific protocol and communicate with the serial device driver. To communicate with the serial device driver, the Serial Protocol Modules use publishedPartner APIs such as <xref href="GUID-3B4E8ED5-72F7-3E51-B188-3C1045526DDF.dita"><apiname>RBusDevComm</apiname></xref>. The <codeph>RBusDevComm</codeph> API provides a handle to a channel to the serial device driver. This device driver only implements the basic data transfer and break operations, and is not intended for use directly by client applications. The device driver is implemented using a Physical Device Driver (PDD) and a Logical Device Driver (LDD). The PDD and LDD must be loaded before a Serial Protocol Module can be used. For a device being tested, the application client may need to load the PDD and LDD. For a device that is shipped, the boot sequence normally loads the LDDs and PDDs. Figure 1 below shows the architecture and the appropriate APIs at each level. Figure 2 below shows the architecture with three Serial Protocol Modules loaded. </p> <fig id="GUID-4F316E33-41C6-5BF4-AAE1-2750C58CC1AA"><title> |
12 <concept id="GUID-107AE89E-901E-535F-8D1A-EE347D7822B1" xml:lang="en"><title>Architecture</title><shortdesc>This topic describes the architecture of the Serial Communications |
13 Figure 1 - The architecture and the appropriate APIs at each level |
13 Server. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
14 </title> <image href="GUID-44ADB485-69C2-5557-AB95-3B6D20870F73_d0e125876_href.png" placement="inline"/></fig> <fig id="GUID-5B17051E-C4E7-5657-BB62-26072FB13D83"><title> |
14 <p>The Serial Communications Server uses the Symbian platform client/server |
15 Figure 2 - The architecture with three CSYs loaded |
15 framework. Clients use <codeph>R</codeph> classes that send requests to the |
16 </title> <image href="GUID-45DD08DB-FCB3-5546-91B4-25868C8ABAE4_d0e125882_href.png" placement="inline"/></fig> <p>Each serial port has a limited availability when multiple clients attempt to use the port. The Serial Communications Server provides some functionality to mediate between competing clients. This mediation is provided by the <xref href="GUID-3B4E8ED5-72F7-3E51-B188-3C1045526DDF.dita"><apiname>RComm::Open()</apiname></xref> and <xref href="GUID-3B4E8ED5-72F7-3E51-B188-3C1045526DDF.dita"><apiname>RComm::OpenWithAvailable()</apiname></xref> APIs. However, the first client to access a port has control. If a client must get access to a serial port, then that client must ensure it connects to the serial port before other clients. The reliable method of ensuring access to a serial port is for a client to connect as part of the device boot procedure. If a client must have access to a serial port, then the device manufacturer should specify which clients access ports during device boot. </p> <section><title>Historical Notes</title> <ol id="GUID-920828D6-9304-5E44-B82D-671097029B21"><li id="GUID-EE61E2E6-EABB-58D1-AE5A-E452589F5D3C"><p>The framework supplied by the Serial Communications Server for Serial Protocol Modules has a narrower set of capabilities compared to the Socket Server for protocol developers. This design decision was taken because prior to Symbian OS 8.0 the Serial Communications Server was originally expected to run for the lifetime of the device while the Socket Server was not. To save resources, for example memory, the Serial Communications Server was designed to load and unload modules as required. </p> <p>Since the introduction of RootServer in Symbian OS 8.0, the Socket Server was changed to run for the lifetime of the device. </p> </li> <li id="GUID-DB979584-6BBE-56AA-8068-FC5650D40A46"><p>In Symbian OS 9.5, the Serial Communications Server was converted into a multi-threaded server. The Serial Protocol Modules can be run in separate threads. This change did not change the behaviour of the Serial Communications Server except for three changes: </p> <ol id="GUID-0BCD64C0-448E-5ACA-9928-AC30E42A59CF"><li id="GUID-5EFB6685-D6E8-53D9-B3B6-5E1A944F4247"><p>A serial protocol module which blocks does not stop other Serial Protocol Modules from running </p> </li> <li id="GUID-71E76203-BA35-5854-AC89-E105BEBDB6B3"><p>A serial protocol module can run faster than other modules by changing the configured thread priority </p> </li> <li id="GUID-B844EEB9-B241-553B-8631-622BDA0B7A84"><p>A serial protocol module can use the Serial Communications Server API and request services of another serial protocol module </p> </li> </ol> </li> </ol> </section> </conbody><related-links><link href="GUID-D0D27AEA-FDDB-5F6F-94F6-ADDF5910DC47.dita"><linktext> |
16 Serial Communications Server. The server in turn passes requests to an appropriate |
17 Client/Server Overview</linktext> </link> </related-links></concept> |
17 plug-in module that handles the particular communication protocol. These plug-in |
|
18 modules are known as <i>Serial Protocol Modules</i> or <i>CSYs</i>. The Serial |
|
19 Protocol Modules are loaded by the Serial Communications server, and are not |
|
20 directly accessed by client applications. A Symbian platform phone may include |
|
21 a number of Serial Protocol Modules as standard, such as for handling RS232 |
|
22 and infra-red serial communications. The Serial Protocol Module API allows |
|
23 new Serial Protocol Modules modules to be developed. </p> |
|
24 <p>The Serial Communications Server provides a publishedAll API to access |
|
25 the serial ports of the device. The Serial Communications Server provides |
|
26 functionality such as timeouts and port sharing for all Serial Protocol Modules. |
|
27 The Serial Protocol Modules provide the specific protocol and communicate |
|
28 with the serial device driver. To communicate with the serial device driver, |
|
29 the Serial Protocol Modules use publishedPartner APIs such as <xref href="GUID-3B4E8ED5-72F7-3E51-B188-3C1045526DDF.dita"><apiname>RBusDevComm</apiname></xref>. |
|
30 The <codeph>RBusDevComm</codeph> API provides a handle to a channel to the |
|
31 serial device driver. This device driver only implements the basic data transfer |
|
32 and break operations, and is not intended for use directly by client applications. |
|
33 The device driver is implemented using a Physical Device Driver (PDD) and |
|
34 a Logical Device Driver (LDD). The PDD and LDD must be loaded before a Serial |
|
35 Protocol Module can be used. For a device being tested, the application client |
|
36 may need to load the PDD and LDD. For a device that is shipped, the boot sequence |
|
37 normally loads the LDDs and PDDs. Figure 1 below shows the architecture and |
|
38 the appropriate APIs at each level. Figure 2 below shows the architecture |
|
39 with three Serial Protocol Modules loaded. </p> |
|
40 <fig id="GUID-4F316E33-41C6-5BF4-AAE1-2750C58CC1AA"> |
|
41 <title> Figure 1 - The architecture and the appropriate APIs at |
|
42 each level </title> |
|
43 <image href="GUID-44ADB485-69C2-5557-AB95-3B6D20870F73_d0e150753_href.png" placement="inline"/> |
|
44 </fig> |
|
45 <fig id="GUID-5B17051E-C4E7-5657-BB62-26072FB13D83"> |
|
46 <title> Figure 2 - The architecture with three CSYs loaded |
|
47 </title> |
|
48 <image href="GUID-45DD08DB-FCB3-5546-91B4-25868C8ABAE4_d0e150761_href.png" placement="inline"/> |
|
49 </fig> |
|
50 <p>Each serial port has a limited availability when multiple clients attempt |
|
51 to use the port. The Serial Communications Server provides some functionality |
|
52 to mediate between competing clients. This mediation is provided by the <xref href="GUID-3B4E8ED5-72F7-3E51-B188-3C1045526DDF.dita"><apiname>RComm::Open()</apiname></xref> and <xref href="GUID-3B4E8ED5-72F7-3E51-B188-3C1045526DDF.dita"><apiname>RComm::OpenWithAvailable()</apiname></xref> APIs. |
|
53 However, the first client to access a port has control. If a client must get |
|
54 access to a serial port, then that client must ensure it connects to the serial |
|
55 port before other clients. The reliable method of ensuring access to a serial |
|
56 port is for a client to connect as part of the device boot procedure. If a |
|
57 client must have access to a serial port, then the device manufacturer should |
|
58 specify which clients access ports during device boot. </p> |
|
59 <section id="GUID-39D0A44F-3E6D-486F-BC72-A4260374419C"><title>Historical Notes</title> <ol id="GUID-920828D6-9304-5E44-B82D-671097029B21"> |
|
60 <li id="GUID-EE61E2E6-EABB-58D1-AE5A-E452589F5D3C"><p>The framework supplied |
|
61 by the Serial Communications Server for Serial Protocol Modules has a narrower |
|
62 set of capabilities compared to the Socket Server for protocol developers. </p> </li> |
|
63 <li id="GUID-DB979584-6BBE-56AA-8068-FC5650D40A46"><p>In Symbian platform, |
|
64 the Serial Communications Server was converted into a multi-threaded server. |
|
65 The Serial Protocol Modules can be run in separate threads. This change did |
|
66 not change the behaviour of the Serial Communications Server except for three |
|
67 changes: </p> <ol id="GUID-0BCD64C0-448E-5ACA-9928-AC30E42A59CF"> |
|
68 <li id="GUID-5EFB6685-D6E8-53D9-B3B6-5E1A944F4247"><p>A serial protocol module |
|
69 which blocks does not stop other Serial Protocol Modules from running </p> </li> |
|
70 <li id="GUID-71E76203-BA35-5854-AC89-E105BEBDB6B3"><p>A serial protocol module |
|
71 can run faster than other modules by changing the configured thread priority </p> </li> |
|
72 <li id="GUID-B844EEB9-B241-553B-8631-622BDA0B7A84"><p>A serial protocol module |
|
73 can use the Serial Communications Server API and request services of another |
|
74 serial protocol module </p> </li> |
|
75 </ol> </li> |
|
76 </ol> </section> |
|
77 </conbody><related-links> |
|
78 <link href="GUID-D0D27AEA-FDDB-5F6F-94F6-ADDF5910DC47.dita"><linktext> |
|
79 Client/Server Overview</linktext></link> |
|
80 </related-links></concept> |