Skip to content

Commit 16fc363

Browse files
jameswalmsleyjameswalmsley
committed
[DOCS] Added a GPIO subsystem documentation.
1 parent a7148f4 commit 16fc363

File tree

5 files changed

+290
-0
lines changed

5 files changed

+290
-0
lines changed

‎_includes/docs_contents.html

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ <h4>Getting Started</h4>
1717
</ul>
1818
<h4>API</h4>
1919
<ul>
20+
<li class="{% if page.title == "GPIO Subsystem" %}current{% endif %}">
21+
<a href="{{ site.url }}/docs/api/gpio">GPIO Subsystem</a>
22+
</li>
23+
2024
<li class="{% if page.title == "Process Manager" %}current{% endif %}">
2125
<a href="{{ site.url }}/docs/api/process">Process Manager</a>
2226
</li>

‎docs/api/gpio/bt_gpioget.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
layout: docs
3+
title: BT_GpioGet()
4+
next_section: api/gpio/bt_gpioset
5+
permalink: /docs/api/gpio/bt_gpioget/
6+
header_path: os/include/gpio/bt_gpio.h
7+
source_path: os/src/gpio/bt_gpio.c
8+
---
9+
10+
Gets the current state of the specified GPIO.
11+
12+
<div class="note info">
13+
<h5>Notes</h5>
14+
<p>
15+
This function will always succeed when given a valid GPIO number.
16+
The provided pError value can be optionally provided and checked.
17+
</p>
18+
</div>
19+
20+
# Parameters
21+
22+
<div class="mobile-side-scroller">
23+
<table>
24+
<thead>
25+
<tr>
26+
<th>Parameter</th>
27+
<th>Description</th>
28+
</tr>
29+
</thead>
30+
<tbody>
31+
32+
<tr>
33+
<td><p><code>ulGPIO</code></p></td>
34+
<td><p>
35+
GPIO number of the GPIO line to be tested.
36+
</p></td>
37+
</tr>
38+
39+
<tr>
40+
<td><p><code>pError</code></p></td>
41+
<td><p>
42+
Pointer to a BT_ERROR variable. Can be NULL.
43+
</p></td>
44+
</tr>
45+
46+
</tbody>
47+
</table>
48+
</div>
49+
50+
# Returns
51+
52+
BT_TRUE or BT_FALSE.
53+
On error, BT_FALSE will be returned, and the BT_ERROR code can be tested from the optionally provided
54+
pError variable.
55+
56+
# Further Reading
57+
58+
The full API is defined under:
59+
60+
{% include api/header-path.md %}
61+
62+
See the implementation under:
63+
{% include api/source-path.md %}

‎docs/api/gpio/bt_gpiogetdirection.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
layout: docs
3+
title: BT_GpioGetDirection()
4+
next_section: api/gpio/bt_gpiosetdirection
5+
permalink: /docs/api/gpio/bt_gpiogetdirection/
6+
header_path: os/include/gpio/bt_gpio.h
7+
source_path: os/src/gpio/bt_gpio.c
8+
---
9+
10+
Gets the current mode / direction of the specified GPIO.
11+
12+
<div class="note info">
13+
<h5>Notes</h5>
14+
<p>
15+
Depending on the actual physical hardware, and the GPIO driver implementation for your platform,
16+
some modes may not be possible / available.
17+
</p>
18+
</div>
19+
20+
# Parameters
21+
22+
<div class="mobile-side-scroller">
23+
<table>
24+
<thead>
25+
<tr>
26+
<th>Parameter</th>
27+
<th>Description</th>
28+
</tr>
29+
</thead>
30+
<tbody>
31+
32+
<tr>
33+
<td><p><code>ulGPIO</code></p></td>
34+
<td><p>
35+
GPIO number of the GPIO line to be tested.
36+
</p></td>
37+
</tr>
38+
39+
<tr>
40+
<td><p><code>pError</code></p></td>
41+
<td><p>
42+
Pointer to a BT_ERROR variable. Can be NULL.
43+
</p></td>
44+
</tr>
45+
46+
</tbody>
47+
</table>
48+
</div>
49+
50+
# Returns
51+
52+
BT_GPIO_DIR_UNKNOWN of failure, otherwise a valid direction ENUM value.
53+
54+
# Valid Directions
55+
{% include api/gpio/directions.md %}
56+
57+
# Further Reading
58+
59+
The full API is defined under:
60+
61+
{% include api/header-path.md %}
62+
63+
See the implementation under:
64+
65+
{% include api/source-path.md %}

‎docs/api/gpio/bt_gpioset.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
layout: docs
3+
title: BT_GpioSet()
4+
next_section: api/gpio/bt_gpiogetdirection
5+
permalink: /docs/api/gpio/bt_gpioset/
6+
header_path: os/include/gpio/bt_gpio.h
7+
source_path: os/src/gpio/bt_gpio.c
8+
---
9+
10+
Sets the state of the specified GPIO.
11+
12+
<div class="note info">
13+
<h5>Notes</h5>
14+
<p>
15+
16+
</p>
17+
</div>
18+
19+
# Parameters
20+
21+
<div class="mobile-side-scroller">
22+
<table>
23+
<thead>
24+
<tr>
25+
<th>Parameter</th>
26+
<th>Description</th>
27+
</tr>
28+
</thead>
29+
<tbody>
30+
31+
<tr>
32+
<td><p><code>ulGPIO</code></p></td>
33+
<td><p>
34+
GPIO number of the GPIO line to be tested.
35+
</p></td>
36+
</tr>
37+
38+
<tr>
39+
<td><p><code>bValue</code></p></td>
40+
<td><p>
41+
BT_TRUE or BT_FALSE.
42+
</p></td>
43+
</tr>
44+
45+
</tbody>
46+
</table>
47+
</div>
48+
49+
# Returns
50+
51+
BT_TRUE or BT_FALSE to represent the GPIO's current state.
52+
On error, BT_FALSE is returned, and pError can be tested.
53+
54+
55+
# Further Reading
56+
57+
The full API is defined under:
58+
59+
{% include api/header-path.md %}
60+
61+
See the implementation under:
62+
{% include api/source-path.md %}

‎docs/api/gpio/gpio.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
layout: docs
3+
title: GPIO Subsystem
4+
next_section: usage-rules
5+
permalink: /docs/api/gpio/
6+
header_path: os/include/gpio/bt_gpio.h
7+
source_path: os/src/gpio/bt_gpio.c
8+
---
9+
10+
The GPIO sub-system in BitThunder is very straight-forward and simple to use.
11+
Throughout the entire system GPIOs are addressed using a GPIO number/flag space.
12+
13+
Depending on your system/application GPIO flags can be mapped and aliased within this
14+
address space. Usually primary GPIOs start at 0, but thats just a convention.
15+
16+
GPIO are accesible to all, and no BT_HANDLE is associated or exported to user-space.
17+
Therefore its possible to have multiple processes conflicting, and controlling the same
18+
GPIO by mistake.
19+
20+
<div class="note info">
21+
<h5>GPIO Anarchy</h5>
22+
<p>
23+
Having the GPIO API in this way makes its usage very simple, and most BitThunder systems are currently
24+
closed embedded systems. However we intend to extend the API later to allow a process to LOCK a GPIO
25+
to itself, and only make use of the GPIO pin using a special HANDLE based API.
26+
</p>
27+
</div>
28+
29+
# User-space API
30+
31+
The following table lists all functions related to the process manager API.
32+
33+
<div class="mobile-side-scroller">
34+
<table>
35+
<thead>
36+
<tr>
37+
<th>API</th>
38+
<th>Description</th>
39+
</tr>
40+
</thead>
41+
<tbody>
42+
43+
<tr>
44+
<td><p><code><a href="{{ site.url }}/docs/api/gpio/bt_gpioget/">BT_GpioGet()</a></code></p></td>
45+
<td><p>
46+
Gets the current state of a GPIO line.
47+
</p></td>
48+
</tr>
49+
50+
<tr>
51+
<td><p><code><a href="{{ site.url }}/docs/api/gpio/bt_gpioset/">BT_GpioSet()</a></code></p></td>
52+
<td><p>
53+
Sets a GPIO line to the desired state.
54+
</p></td>
55+
</tr>
56+
57+
<tr>
58+
<td><p><code><a href="{{ site.url }}/docs/api/gpio/bt_gpiogetdirection/">BT_GpioGetDirection()</a></code></p></td>
59+
<td><p>
60+
Gets the direction / mode of a GPIO line.
61+
</p></td>
62+
</tr>
63+
64+
<tr>
65+
<td><p><code><a href="{{ site.url }}/docs/api/gpio/bt_gpiosetdirection/">BT_GpioSetDirection()</a></code></p></td>
66+
<td><p>
67+
Sets the direction / mode of a GPIO line.
68+
</p></td>
69+
</tr>
70+
71+
</tbody>
72+
</table>
73+
</div>
74+
75+
# Kernel-space / Driver API
76+
77+
<div class="mobile-side-scroller">
78+
<table>
79+
<thead>
80+
<tr>
81+
<th>API</th>
82+
<th>Description</th>
83+
</tr>
84+
</thead>
85+
<tbody>
86+
87+
<tr>
88+
<td><p><code><a href="{{ site.url }}/docs/api/gpio/bt_registergpiocontroller/">BT_RegisterGpioController()</a></code></p></td>
89+
<td><p>
90+
Registers a GPIO controller driver with the GPIO sub-system.
91+
</p></td>
92+
</tr>
93+
94+
</tbody>
95+
</table>
96+
</div>

0 commit comments

Comments
 (0)