Skip to content

Commit

Permalink
📝 Updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
@PhazonicRidley
PhazonicRidley committed May 10, 2024
1 parent 4ec3ee4 commit fecc7f5
Show file tree
Hide file tree
Showing 3 changed files with 87 additions and 148 deletions.
2 changes: 1 addition & 1 deletion Dockerfile
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
FROM --platform=arm64 ubuntu:22.04

RUN apt update && apt upgrade -y
RUN apt install gcc g++ valgrind neofetch git wget python3-pip clang-format software-properties-common locales pkg-config automake autoconf autoconf-archive libtool m4 -y
RUN apt install gcc g++ valgrind neofetch git wget python3-pip clang-format software-properties-common locales pkg-config automake autoconf autoconf-archive libtool m4 clangd-17 -y

RUN wget https://apt.llvm.org/llvm.sh
RUN chmod +x llvm.sh
Expand Down
171 changes: 24 additions & 147 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,15 @@
# libhal-linux
> [!IMPORTANT]
> There is not yet a published package on JFrog and you will need to build the package manually using `conan create . --version=latest`. This will be fixed soon.
> No cross compiler profiles have been created yet, to use develop using this you currently need develop with the same archtecture and operating system as your build target. A Dockerfile has been provided for arm64 linux development. (Raspberry Pis and alike)
[![✅ Checks](https://github.com/libhal/libhal-linux/actions/workflows/ci.yml/badge.svg)](https://github.com/libhal/libhal-linux/actions/workflows/ci.yml)
[![Coverage](https://libhal.github.io/libhal-linux/coverage/coverage.svg)](https://libhal.github.io/libhal-linux/coverage/)
[![GitHub stars](https://img.shields.io/github/stars/libhal/libhal-linux.svg)](https://github.com/libhal/libhal-linux/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/libhal/libhal-linux.svg)](https://github.com/libhal/libhal-linux/network)
[![GitHub issues](https://img.shields.io/github/issues/libhal/libhal-linux.svg)](https://github.com/libhal/libhal-linux/issues)

Platform library for linux series of devices.
Userspace library for embedded linux

## Contributing

Expand All @@ -18,161 +21,35 @@ Apache 2.0; see [`LICENSE`](LICENSE) for details.

---

## Making a new platform driver (Delete section below)
## 📚 Software APIs & Usage
To learn about available kernel APIs, documentation will be be made available soon.

Use [libhal/libhal-lpc40](https://github.com/libhal/libhal-lpc40/) as an
example of the sections a README should have.
To see some example code on how various APIs are used, see the programs inside the `demos` folder.

To make your own libhal library:
## 🧰 Setup

1. Press the green "Use this Template" button then.
2. Press the "Create a new repository".
3. Name it `libhal-<insert_platform_name>` and replace `<insert_platform_name>`
with the name of the device's family. For exmaple, if you want to make a
library for the stm32f103 which is in the stm32f1 series of MCUs then call
it `libhal-stm32f1`.
4. Choose where to put the repo under.
5. Go to `settings` > `Pages` > `Build and deployment` > `Source` and set the
source to `Github Actions`.
6. Go to `Pull Requests` and merge the library rename pull request.
7. Done!
Following the
[🚀 Getting Started](https://libhal.github.io/2.1/getting_started/)
instructions.

## About the libhal-platform template
## 📡 Installing Profiles

The `libhal-linux` repository is a template for creating platform
libraries in the libhal ecosystem. It provides a structured layout and a set of files to help you get started with creating your own platform library.
Coming soon, see important notice.

## .github/workflows
## 🏗️ Building Demos

This directory contains GitHub Actions workflow files for continuous integration
(CI) and other automated tasks. The workflows currently included are:
**ON the device that is to run this code, a computer that is the same OS and architecture, or inside the provided docker container:**

- `ci.yml`: This workflow runs the CI pipeline, which includes
building the project, running tests, and deploying the library to the
`libhal-trunk` package repository.
- `take.yml`: This workflow is responsible for the "take" action, which assigns
commits to
- `deploy-version.yml`: A helper CI workflow that builds the library for each
target architecture/os/etc.
- `0.0.1.yml`: A launch file. This file is used to manually release a version
of the project via the "work dispatch" function of github actions.
- `update_name.yml`: This workflow updates the name of the repository when it's
used as a template for a new repository.

## conanfile.py

This is a [Conan](https://conan.io/) recipe file. Conan is a package manager for
C and C++ that helps manage dependencies in your project. This file defines how
Conan should build your project and its dependencies.

### Update topics

Add more tags to the `topics` attribute of your the file.

### Setting the processor library

The default processor library used is `libhal-armcortex`. Replace the follow
code block in the file with the appropriate processor library.

```python
# Replace with appropriate processor library
self.requires("libhal-armcortex/[^3.0.2]")
To build demos, start at the root of the repo and execute the following command:
```bash
conan build demos
```

### Adding available platforms

```python
options = {
"platform": [
"profile1",
"profile2",
"not-me"
],
}
```

Replace `"profile1"` and `"profile2"` with the exact names of each platform in
the platform's family. For example, in the `stm32f1` family of microcontrollers
there are `stm32f100`, `stm32f101`, `stm32f102`, `stm32f103`, `stm32f105`, and
`stm32f107`.

Keep `default_options` as it is.

## linker_scripts/libhal-linux

This directory contains linker scripts for different configurations of the
platform. Each linker script specifies how the linker should arrange the
sections of the program in memory.

Each platform specified in the `conanfile.py` file must have a corresponding
linker script in this directory. For example, the `stm32f1` family of
microcontrollers would have `stm32f100.ld`, `stm32f101.ld`, `stm32f102.ld`,
`stm32f103.ld`, `stm32f105.ld`, and `stm32f107.ld`.

For details of how these linker scripts should be composed in your library,
please see the documentation for the processor library used for the platform.
Usually this information is put in the processor library's README.md.

## conan/profiles

This directory contains Conan profiles for different configurations of the
platform. Each profile specifies a set of settings and options that Conan should
use when building the project.
## 💾 Flashing/Programming

Each platform specified in the `conanfile.py` file must have a corresponding
profile in this directory. Using the `stm32f1` family as an example, you will
have the following profiles: `stm32f100`, `stm32f101`, `stm32f102`, `stm32f103`,
`stm32f105`, `stm32f107`.
The easiest way to get your compiled program onto hardware like a Raspberry Pi is via ssh. (Assuming your hardware's linux installation has sshd).

For details of how these profiles should be composed in your library,
please see the documentation for the processor library used for the platform.
Usually this information is put in the processor library's README.md.

## datasheets

This directory is intended for storing data sheets related to the platform that
the library is being built for. It currently contains a placeholder file,
`placeholder.txt`.

Many data sheets are subject to copyright and that must be considered when
adding the data sheet to a libhal repo. If the data sheet cannot be
redistributed on the repo for copyright and/or license reasons, then a markdown
file with a link to the data sheet (and potentially mirrors of it) is an
acceptable alternative.

## demos

This directory contains demonstration applications showing how to use the
platform library. It includes:

- `applications/blinker.cpp`: A sample application demonstrating usage of the
platform library.
- `main.cpp`: The main entry point for the demo applications.

## include/libhal-linux

This directory contains the header files for the platform library. It currently
includes `output_pin.hpp`, which is a placeholder for the main header file of
your platform library.

## src

This directory contains the source files for the platform library. It currently
includes `output_pin.cpp`, which is a placeholder for drivers for this platform
library.

## test_package

This directory contains a test package for the Conan recipe. It includes a
simple application that uses the platform library, which helps verify that the
Conan recipe is working correctly.

## tests

This directory contains tests for the platform library. It includes:

- `linux.test.cpp`: A placeholder for tests for the platform library.
- `main.test.cpp`: The main entry point for the tests.

Remember to replace all instances of `linux` with the actual name of the
platform that your library is being built for.
Run the following command:
```bash
scp path/to/your.bin username@hardware_device:new_path/to/app
```
62 changes: 62 additions & 0 deletions demos/compile_commands 2.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
[
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_gpio.dir/main.cpp.o -c /code/demos/main.cpp",
"file": "/code/demos/main.cpp",
"output": "CMakeFiles/linux_demos_gpio.dir/main.cpp.o"
},
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_gpio.dir/applications/gpio.cpp.o -c /code/demos/applications/gpio.cpp",
"file": "/code/demos/applications/gpio.cpp",
"output": "CMakeFiles/linux_demos_gpio.dir/applications/gpio.cpp.o"
},
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_blinker.dir/main.cpp.o -c /code/demos/main.cpp",
"file": "/code/demos/main.cpp",
"output": "CMakeFiles/linux_demos_blinker.dir/main.cpp.o"
},
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_blinker.dir/applications/blinker.cpp.o -c /code/demos/applications/blinker.cpp",
"file": "/code/demos/applications/blinker.cpp",
"output": "CMakeFiles/linux_demos_blinker.dir/applications/blinker.cpp.o"
},
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_i2c_test.dir/main.cpp.o -c /code/demos/main.cpp",
"file": "/code/demos/main.cpp",
"output": "CMakeFiles/linux_demos_i2c_test.dir/main.cpp.o"
},
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_i2c_test.dir/applications/i2c_test.cpp.o -c /code/demos/applications/i2c_test.cpp",
"file": "/code/demos/applications/i2c_test.cpp",
"output": "CMakeFiles/linux_demos_i2c_test.dir/applications/i2c_test.cpp.o"
},
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_uart.dir/main.cpp.o -c /code/demos/main.cpp",
"file": "/code/demos/main.cpp",
"output": "CMakeFiles/linux_demos_uart.dir/main.cpp.o"
},
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_uart.dir/applications/uart.cpp.o -c /code/demos/applications/uart.cpp",
"file": "/code/demos/applications/uart.cpp",
"output": "CMakeFiles/linux_demos_uart.dir/applications/uart.cpp.o"
},
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_steady_clock_test.dir/main.cpp.o -c /code/demos/main.cpp",
"file": "/code/demos/main.cpp",
"output": "CMakeFiles/linux_demos_steady_clock_test.dir/main.cpp.o"
},
{
"directory": "/code/demos/build/unspecified/Release",
"command": "/usr/bin/clang++-17 -I/code/demos/. -isystem /root/.conan2/p/b/libhaf431e523fb55f/p/include -isystem /root/.conan2/p/b/libhac2ef268c2495b/p/include -isystem /root/.conan2/p/libha6f1566c3082ef/p/include -isystem /root/.conan2/p/tl-fu31454aa876889/p/include -stdlib=libc++ -O3 -DNDEBUG -std=c++23 -o CMakeFiles/linux_demos_steady_clock_test.dir/applications/steady_clock_test.cpp.o -c /code/demos/applications/steady_clock_test.cpp",
"file": "/code/demos/applications/steady_clock_test.cpp",
"output": "CMakeFiles/linux_demos_steady_clock_test.dir/applications/steady_clock_test.cpp.o"
}
]

0 comments on commit fecc7f5

Please sign in to comment.