BareMetal-C

Bare Metal C: C99 Style Guide

Language: C (SDCC Compiler/C99 Standard)

---

0. Prerequisite

Read the C99 Coding Guidelines document first.

1. Core Philosophy

Moving from Python to C requires a shift in mindset. In C, you are managing the hardware directly. There is no automatic memory management, and safety features must be added by you, the programmer.

• Be Explicit: Nothing happens automatically. If you want a variable to be zero, you must set it to zero.
• Be Safe: Use types that prevent errors before they happen.
• Be Readable: Code is read much more often than it is written.

---

2. File Organization

• Header Guards: Every .h file must be wrapped in generic include guards to prevent recursive inclusion.
• Includes: System headers (< >) go first, followed by project headers (" ").
• Comment Style: Use C99-style single-line comments (//) for general notes and descriptions. Avoid multi-line C-style comments (/* ... */) unless commenting out large blocks of code.

#ifndef SENSOR_H
#define SENSOR_H

#include <stdint.h>
#include <stdbool.h>
#include "hardware_map.h"

// Prototypes go here

#endif

---

3. Formatting & Indentation

• Indentation: Use 4 Spaces. Do not use tab characters. Configure your text editor (VS Code/SimulIDE) to “Insert Spaces” when pressing Tab.
• Braces: Use “One True Brace Style” (OTBS) (opening brace on the same line). Always use braces, even for single-line statements.
• One Statement Per Line: Never combine logic or block formatting onto a single line. Why: This improves readability and ensures step-through debuggers can stop at every specific action.

Bad (Hard to read/debug):

if (ready) { go = true; } else { go = false; }

Good:

if (ready) {
    go = true;
} else {
    go = false;
}

• Closing Braces Alignment: Closing braces (}) must vertically align with the line that opens the brace ({) Why: This maintains clear visual block structure and prevents the “dangling else” error where the else accidentally attaches to the wrong if statement.

Bad (Dangling Else Risk):

if (a > 0)
    if (b > 0)
        c = 1;
else
    c = 0; // This 'else' attaches to the second 'if (b > 0)'!

Good: Correctly resolves the ambiguity by making the compiler’s default choice explicit.

if (a > 0) {
    if (b > 0) {
        c = 1;
    } else {
        c = 0;
    }
}

Use cascaded if-else:

When else is immediately followed by if, it is a good idea to not use { right after else, as this can make the code hard to read:

Good: easy to understand:

if (bitcoin >= 20) {
    class = PLATINUM;
} else if (bitcoin >= 10) {
    class = GOLD;
} else if (bitcoin >= 5) {
    class = SILVER;
} else {
    class = REGULAR;
}

Bad: indentation makes it hard to read:

if (bitcoin >= 20) {
    class = PLATINUM;
} else {
    if (bitcoin >= 10) {
        class = GOLD;
    } else {
        if (bitcoin >= 5) {
            class = SILVER;
        } else {
            class = REGULAR;
        }
    }
}

---

4. Data Types & Const Correctness

Do not use generic int or long. In embedded systems, we need to know exactly how many bits a number uses.

4.1 Strict Types

Always include and .

Type	Description	Use Case
uint8_t	Unsigned 8-bit (0 to 255)	Hardware registers, bytes, flags.
int8_t	Signed 8-bit (-128 to 127)	Small math values.
uint16_t	Unsigned 16-bit (0 to 65,535)	Counters, memory addresses.
bool	Boolean (true/false)	Logical checks.
void	Empty/Nothing	Functions returning nothing.

4.2 Const by Default

Variables should be immutable (const) by default. Only remove const if the variable must change (e.g., a counter or accumulator).

• Why? This prevents accidental changes later in the program (a common source of bugs) and allows the compiler to optimize how it uses limited memory.
• Rule: If you don’t assign a new value to it after initialization, it must be const.

const uint8_t max_retries = 5;  // Good: This is a fixed setting
uint8_t current_retry = 0;      // Good: This changes in a loop

---

5. Naming Conventions

• Variables & Functions: Use snake_case (lowercase with underscores).
  • uint8_t sensor_value;
  • void read_data(void);
• Constants & Macros: Use UPPER_CASE.
  • #define MAX_BUFFER 255
  • const uint8_t LED_PIN_INDEX = 1U;
• Pointer Spacing:
  • Standard Pointers: Attach the asterisk (*) to the variable name.
    • Good: uint8_t *data_ptr;
    • Bad: uint8_t* data_ptr;
  • Const Pointers: If the pointer itself is immutable (* const), place the asterisk immediately before the const keyword.
    • Example: uint8_t * const lcd_buffer = (uint8_t *)0xE000U;

---

6. Functions & Scope

• Explicit Void: Functions taking no arguments must explicitly use void.
  • int32_t calculate_sum(void);
• Variable Scope: Declare loop counters inside the loop definition (C99 feature) to keep them local to the block.

  // Use explicit assignment (i = i + 1) to comply with the rule against composite operators.
  for (uint8_t i = 0; i < 10; i = i + 1) {
      // ...
  }
  

• Header Prototypes: All function prototypes must be declared in a header file (.h) before use in a source file (.c). C is compiled sequentially, unlike Python.

---

7. Python vs. C Cheat Sheet

Feature	Python	C99 Guideline
Blocks	Indentation	Curly Braces { } (Indentation is purely visual)
True/False	True / False	true / false (requires <stdbool.h>)
Variables	Dynamic (x = 5)	Static (const uint8_t x = 5;)
Strings	“Hello”	Array of chars (const char msg[] = "Hello";)
Printing	print("Val:", x)	uart_transmit_byte(x);
Main	if __name__ == "__main__":	void main(void) { ... }

This site is open source. Improve this page.