README.md
1<!--
2 Copyright 2020, Data61
3 Commonwealth Scientific and Industrial Research Organisation (CSIRO)
4 ABN 41 687 119 230.
5
6 This software may be distributed and modified according to the terms of
7 the BSD 2-Clause license. Note that NO WARRANTY is provided.
8 See "LICENSE_BSD2.txt" for details.
9
10 @TAG(DATA61_BSD)
11-->
12
13# GPIOMUXServer
14
15This is a CAmkES component that is intended to abstract over a platform's GPIO
16and pin multiplexer controller, and multiplex client access to it.
17
18## Dependencies
19
20This component needs to be used with the `single-threaded` module that performs
21the initialisation process, and client request routing the component relies on.
22
23## Usage
24
25For clients to use the functionality exposed by the component, the clients will
26have to connect to the CAmkES interfaces that the following CPP defintions
27expose.
28
29```c
30GPIOServer_server_interfaces(the_gpio)
31MUXServer_server_interfaces(the_mux)
32```
33
34The definitions exposes a `GPIO` and `MUX` RPC interface that is expected to be
35connected via the `seL4RPCNoThreads` connector. However, there are helper
36macros which simplifies this process and also registers a GPIO and mux
37interface on the client's interface registration service
38(`ps_interface_ops_t`).
39
40```c
41ClockServer_client_connections(client_name, client, server_name, server)
42MUXServer_client_connections(client_name, client, server_name, server)
43```
44
45## Supported platforms
46
47Currently, this component supports the following platforms:
48 - Exynos5-based platforms (Odroid XU, Odroid XU4)
49 - TX2
50
51Additional platforms require a corresponding GPIO and pin multiplexer
52controller driver to be implemented in the libplatsupport library of the
53[`util_libs`](https://github.com/seL4/util_libs) repository, and the following
54CPP defintions to be created in the `include` folder of this component:
55 - `HARDWARE_GPIO_COMPONENT`
56 - `HARDWARE_GPIO_INTERFACES`
57 - `HARDWARE_GPIO_ATTRIBUTES`
58 - `HARDWARE_GPIO_COMPOSITION`
59 - `HARDWARE_GPIO_CONFIG`
60 - `HARDWARE_MUX_COMPONENT`
61 - `HARDWARE_MUX_INTERFACES`
62 - `HARDWARE_MUX_ATTRIBUTES`
63 - `HARDWARE_MUX_COMPOSITION`
64 - `HARDWARE_MUX_CONFIG`
65
66## Limitations
67
68The pin multiplexing part of the component may interfere with the GPIO part of
69the component, that is, if a client requests that a feature be switched on via
70the pin multiplexer, another client may lose access to a GPIO pin. There is no
71form of access control with regards to both the GPIO pins and the pin
72multiplexer features.
73