Skip to content

Commit

Permalink
📝 Add ARCHITECTURE.md
Browse files Browse the repository at this point in the history
- Remove extra variables from CMakeLists
  • Loading branch information
kammce committed Aug 12, 2024
1 parent 827a00c commit e2732e3
Show file tree
Hide file tree
Showing 3 changed files with 93 additions and 51 deletions.
65 changes: 65 additions & 0 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# libhal starter architecture

## `src/main.cpp`

It contains the main loop of the application. In this example, it just prints
"Hello, World" and toggles an LED on and off. This application will reset after
10 iterators just to demonstrate the capability.

## `include/application.hpp`

This file defines the `resource_list` structure which holds optional pointers
to the led, console, clock interfaces and reset callback. Modify this structure
to change the set of required drivers, settings, and memory resources for the
application. `initialize_platform` functions that must be implemented in the
`platform/` file.

## `CMakeLists.txt`

This is the build file for the project. It sets the minimum required version of
CMake, names the project, and sets the platform library. It also defines the
sources to compile and the libraries to link against. Finally, it sets up the
post-build steps with `libhal_post_build`.

### Profile Environment Variables

At the start of the cmake file you will encounter these lines:

```cmake
# Always check that the $ENV{LIBHAL_PLATFORM_LIBRARY} & $ENV{LIBHAL_PLATFORM}
# environment variables are set by the profile.
if("$ENV{LIBHAL_PLATFORM_LIBRARY}" STREQUAL "")
message(FATAL_ERROR
"Build environment variable LIBHAL_PLATFORM_LIBRARY is required for " "this project.")
endif()
if("$ENV{LIBHAL_PLATFORM}" STREQUAL "")
message(FATAL_ERROR
"Build environment variable LIBHAL_PLATFORM is required for "
"this project.")
endif()
```

libhal conan profiles utilize environment variables as a generic means to
communicate to build systems the name of the libhal binary package,
`$ENV{LIBHAL_PLATFORM_LIBRARY}` and the name of the target platform
`$ENV{LIBHAL_PLATFORM}`. If the developer wishes to use a different build
system compatible with conan, they will need to use their build system's means
to acquire environment variables in order link against the correct library and
select the correct platform source file.

## `platforms/lpc4078.cpp`

This file provides an implementation for `initialize_platform`, for the
`LPC4078` platform. In `initialize_platform`, it sets the clock speed,
configures a uart peripheral for console output, and sets up an output pin for
the led. Each driver is statically allocated. The returned `resource_list` has
the pointers to each statically allocated peripheral and a reset callback that
can resets the microcontroller.

### `platforms/*.cpp`

Just like `platforms/lpc4078.cpp` but for any other platforms. It's important
to note that the specifics of the `initialize_platform` function and the
peripherals used will likely vary between different platforms but sometimes
they don't. As an example the `lpc4074.cpp` file just includes directly the
`lpc4078.cpp` because those are identical.
16 changes: 7 additions & 9 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -16,32 +16,30 @@ cmake_minimum_required(VERSION 3.25)

project(app.elf LANGUAGES CXX)

set(platform_library $ENV{LIBHAL_PLATFORM_LIBRARY})
set(platform $ENV{LIBHAL_PLATFORM})

if("${platform_library}" STREQUAL "")
# Always check that the $ENV{LIBHAL_PLATFORM_LIBRARY} & $ENV{LIBHAL_PLATFORM}
# environment variables are set by the profile.
if("$ENV{LIBHAL_PLATFORM_LIBRARY}" STREQUAL "")
message(FATAL_ERROR
"Build environment variable LIBHAL_PLATFORM_LIBRARY is required for " "this project.")
endif()

if("${platform}" STREQUAL "")
if("$ENV{LIBHAL_PLATFORM}" STREQUAL "")
message(FATAL_ERROR
"Build environment variable LIBHAL_PLATFORM is required for "
"this project.")
endif()

find_package(libhal-${platform_library} REQUIRED CONFIG)
find_package(libhal-$ENV{LIBHAL_PLATFORM_LIBRARY} REQUIRED CONFIG)
find_package(libhal-util REQUIRED CONFIG)

add_executable(${PROJECT_NAME}
src/main.cpp
platforms/${platform}.cpp
platforms/$ENV{LIBHAL_PLATFORM}.cpp
)

target_compile_options(${PROJECT_NAME} PRIVATE -g -Wall -Wextra --save-temps)
target_include_directories(${PROJECT_NAME} PUBLIC include .)
target_link_libraries(${PROJECT_NAME} PRIVATE
libhal::${platform_library}
libhal::$ENV{LIBHAL_PLATFORM_LIBRARY}
libhal::util)

libhal_post_build(${PROJECT_NAME})
Expand Down
63 changes: 21 additions & 42 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,23 @@
# libhal-starter

Before getting started, if you haven't used libhal before, follow the
[Getting Started](https://libhal.github.io/getting_started/) guide.
[Getting Started](https://libhal.github.io/latest/getting_started/) guide.

## 📥 Installing Platform Profiles

For ARM MCU profiles:

```bash
conan config install -sf conan/profiles/v1 -tf profiles https://github.com/libhal/libhal-arm-mcu.git
```

`micromod` profiles:

```bash
conan config install -sf conan/profiles/v1 -tf profiles https://github.com/libhal/libhal-micromod.git
```

## 🏗️ Building Application

To build the project:

Expand All @@ -21,53 +37,16 @@ For the STM32F103 MicroMod V4:
conan build . -pr mod-stm32f1-v4 -pr arm-gcc-12.3
```

## Supported platforms
## Supported platforms

- lpc4078
- lpc4074
- stm32f103c8
- micromod
- lpc4078 MicroMod V5
- stm32f103c8 MicroMod V4
- stm32f103c8 MicroMod V5

## Installing Platform Profiles

For ARM MCU profiles:

```bash
conan config install -sf conan/profiles/v1 -tf profiles https://github.com/libhal/libhal-arm-mcu.git
```

`micromod` profiles:

```bash
conan config install -sf conan/profiles/v1 -tf profiles https://github.com/libhal/libhal-micromod.git
```
## 🤔 Wondering how is this repo organized?

## Description of Files

1. `main.cpp`: It contains the main loop of the application. In this
example, it just prints "Hello, World" and toggles an LED on and off. This
application will reset after 10 iterators just to demonstrate the capability.
2. `application.hpp`: This file defines the `resource_list` structure which
holds optional pointers to the led, console, clock interfaces and reset
callback. Modify this structure to change the set of required drivers,
settings, and memory resources for the application. `initialize_platform`
functions that must be implemented in the `platform/` file.
3. `CMakeLists.txt`: This is the build file for the project. It sets the minimum
required version of CMake, names the project, and sets the platform library.
It also defines the sources to compile and the libraries to link against.
Finally, it sets up the post-build steps with `libhal_post_build`.
4. `platforms/lpc4078.cpp`: This file provides an implementation for
`initialize_platform`, for the LPC4078 platform. In `initialize_platform`,
it sets the clock speed, configures a uart peripheral for console output,
and sets up an output pin for the led. Each driver is statically allocated.
The returned `resource_list` has the pointers to each statically allocated
peripheral and a reset callback that can resets the microcontroller.
5. `platforms/*.cpp`: Just like `platforms/lpc4078.cpp` but for any other
platforms. It's important to note that the specifics of the
`initialize_platform` function and the peripherals used will likely vary
between different platforms but sometimes they don't. As an example the
`lpc4074.cpp` file just includes directly the `lpc4078.cpp` because those
are identical.
See our [`ARCHITECTURE.md`](./ARCHITECTURE.md) to learn about the important
files in the project, what they do, and quirks about how they work.

0 comments on commit e2732e3

Please sign in to comment.