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# fdt-bind-driver
13
14This is a CAmkES driver module that specifies a list of devices to intialize
15drivers for.
16
17Each driver needs to have been declared with `PS_DRIVER_MODULE_DEFINE` that is
18defined in `libplatsupport`. During initialization of the component, the device
19tree will be parsed and if a driver has been defined with a valid compatibility
20string then an attempt will be made to intialize the driver.
21
22## Dependencies
23
24This module needs to be used with the `single-threaded` module that performs
25the intialization process this module relies on.
26
27## Camkes module API
28
29The following CPP definitions create the required interfaces and connection instances
30that implement this module for a component. This module can only be added once to
31each component. Multiple device paths can be given to the driver to select multiple
32devices.
33
34```c
35/**
36 * @brief Declare component interfaces and default list of devices
37 *
38 * @param default_bind_paths The default bind paths
39 */
40fdt_bind_drivers_interfaces(string default_bind_paths[]);
41
42/**
43 * Creates internal component connections
44 */
45fdt_bind_driver_connections();
46
47/**
48 * @brief Configure the module
49 *
50 * @param instance The name of the component instance.
51 * @param devices A list of paths in the device tree describing the
52 * system.
53 */
54fdt_bind_driver_configuration_override(string instance, string devices[]);
55```
56
57
58## Usage
59
60The following shows a driver's partial intialization function's implementation and
61how it is registered as a possible intialization function for devices with valid
62compatibility strings.
63
64```c
65
66#include <platsupport/driver_module.h>
67
68static int uart_pl011_init(ps_io_ops_t *io_ops, const char *device_path)
69{
70 // ...
71
72 return 0;
73}
74
75static const char*compatible_strings[] = {
76 "arm,pl011",
77 NULL
78};
79
80
81PS_DRIVER_MODULE_DEFINE(uart_pl011, compatible_strings, uart_pl011_init);
82
83```
84
85A CMake configuration is required to force the driver to be linked into the final component binary.
86
87```cmake
88# Force the driver module definition to be linked into final binary
89target_link_libraries(driver_library "-Wl,--undefined=uart_pl011_ptr")
90```
91
92The camkes component definition can provide a default list of devices to bind to.
93This can then be overridden on a per instance basis.
94
95```c
96
97#include <camkes-fdt-bind-driver.h>
98
99component Driver {
100 // ..
101 fdt_bind_drivers_interfaces(["/soc/uart@f7112000"]);
102
103 composition {
104 // ...
105 fdt_bind_driver_connections();
106 }
107
108}
109
110
111assembly {
112 composition {
113 component Driver uarta;
114 }
115 configuration {
116 fdt_bind_driver_configuration_override(uarta, ["/soc/uart@f8015000"]);
117 }
118}
119
120```
121