Doc comments and explanations
This commit is contained in:
+12
-39
@@ -25,7 +25,7 @@ const char *const rsc_names[] = {
|
||||
// (determines the logic in the name generation code below)
|
||||
COMPILER_ASSERT(R_EXTI0 > R_PA0);
|
||||
|
||||
/** Get rsc name */
|
||||
|
||||
const char * rsc_get_name(Resource rsc)
|
||||
{
|
||||
assert_param(rsc < RESOURCE_COUNT);
|
||||
@@ -51,7 +51,7 @@ const char * rsc_get_name(Resource rsc)
|
||||
return rsc_names[rsc];
|
||||
}
|
||||
|
||||
/** Get rsc owner name */
|
||||
|
||||
const char * rsc_get_owner_name(Resource rsc)
|
||||
{
|
||||
assert_param(rsc < RESOURCE_COUNT);
|
||||
@@ -61,9 +61,7 @@ const char * rsc_get_owner_name(Resource rsc)
|
||||
return pUnit->name;
|
||||
}
|
||||
|
||||
/**
|
||||
* Initialize the resources registry
|
||||
*/
|
||||
|
||||
void rsc_init_registry(void)
|
||||
{
|
||||
for(uint32_t i = 0; i < RSCMAP_LEN; i++) {
|
||||
@@ -73,13 +71,7 @@ void rsc_init_registry(void)
|
||||
rsc_initialized = true;
|
||||
}
|
||||
|
||||
/**
|
||||
* Claim a resource for a unit
|
||||
*
|
||||
* @param unit - claiming unit
|
||||
* @param rsc - resource to claim
|
||||
* @return true on successful claim
|
||||
*/
|
||||
|
||||
error_t rsc_claim(Unit *unit, Resource rsc)
|
||||
{
|
||||
assert_param(rsc_initialized);
|
||||
@@ -113,14 +105,7 @@ error_t rsc_claim(Unit *unit, Resource rsc)
|
||||
return E_SUCCESS;
|
||||
}
|
||||
|
||||
/**
|
||||
* Claim a range of resources for a unit (useful for GPIO)
|
||||
*
|
||||
* @param unit - claiming unit
|
||||
* @param rsc0 - first resource to claim
|
||||
* @param rsc1 - last resource to claim
|
||||
* @return true on complete claim, false if any failed (none are claimed in that case)
|
||||
*/
|
||||
|
||||
error_t rsc_claim_range(Unit *unit, Resource rsc0, Resource rsc1)
|
||||
{
|
||||
assert_param(rsc_initialized);
|
||||
@@ -136,6 +121,7 @@ error_t rsc_claim_range(Unit *unit, Resource rsc0, Resource rsc1)
|
||||
return E_SUCCESS;
|
||||
}
|
||||
|
||||
|
||||
error_t rsc_claim_gpios(Unit *unit, char port_name, uint16_t pins)
|
||||
{
|
||||
bool suc = true;
|
||||
@@ -151,6 +137,7 @@ error_t rsc_claim_gpios(Unit *unit, char port_name, uint16_t pins)
|
||||
return E_SUCCESS;
|
||||
}
|
||||
|
||||
|
||||
error_t rsc_claim_pin(Unit *unit, char port_name, uint8_t pin)
|
||||
{
|
||||
bool suc = true;
|
||||
@@ -160,12 +147,7 @@ error_t rsc_claim_pin(Unit *unit, char port_name, uint8_t pin)
|
||||
return E_SUCCESS;
|
||||
}
|
||||
|
||||
/**
|
||||
* Free a resource for other use
|
||||
*
|
||||
* @param unit - owning unit; if not null, free only resources claimed by this unit
|
||||
* @param rsc - resource to free
|
||||
*/
|
||||
|
||||
void rsc_free(Unit *unit, Resource rsc)
|
||||
{
|
||||
assert_param(rsc_initialized);
|
||||
@@ -196,13 +178,7 @@ void rsc_free(Unit *unit, Resource rsc)
|
||||
RSC_FREE(global_rscmap, rsc);
|
||||
}
|
||||
|
||||
/**
|
||||
* Free a range of resources (useful for GPIO)
|
||||
*
|
||||
* @param unit - owning unit; if not null, free only resources claimed by this unit
|
||||
* @param rsc0 - first resource to free
|
||||
* @param rsc1 - last resource to free
|
||||
*/
|
||||
|
||||
void rsc_free_range(Unit *unit, Resource rsc0, Resource rsc1)
|
||||
{
|
||||
assert_param(rsc_initialized);
|
||||
@@ -215,12 +191,7 @@ void rsc_free_range(Unit *unit, Resource rsc0, Resource rsc1)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Tear down a unit - release all resources owned by the unit.
|
||||
* Also de-init all GPIOs
|
||||
*
|
||||
* @param unit - unit to tear down; free only resources claimed by this unit
|
||||
*/
|
||||
|
||||
void rsc_teardown(Unit *unit)
|
||||
{
|
||||
assert_param(rsc_initialized);
|
||||
@@ -235,6 +206,8 @@ void rsc_teardown(Unit *unit)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
// build the pins part of the PINOUT.TXT file
|
||||
void rsc_print_all_available(IniWriter *iw)
|
||||
{
|
||||
if (iw->count == 0) return;
|
||||
|
||||
+81
-7
@@ -1,6 +1,16 @@
|
||||
//
|
||||
// Created by MightyPork on 2017/11/24.
|
||||
//
|
||||
// Resource repository. Provides routines for claiming and releasing resources,
|
||||
// resource listing, owner look-up etc.
|
||||
//
|
||||
// Resource is a peripheral or a software facility with exclusive access.
|
||||
//
|
||||
// Resources are assigned to:
|
||||
// - PLATFORM if they're not available
|
||||
// - SYSTEM if they're claimed internally (e.g. status LED pin)
|
||||
// - individual user-defined units
|
||||
//
|
||||
|
||||
#ifndef GEX_RESOURCES_H
|
||||
#define GEX_RESOURCES_H
|
||||
@@ -10,18 +20,45 @@
|
||||
#include "rsc_enum.h"
|
||||
|
||||
#if DEBUG_RSC
|
||||
#define rsc_dbg(fmt, ...) dbg("[RSC] "fmt, ##__VA_ARGS__)
|
||||
#define rsc_dbg(fmt, ...) dbg("[RSC] "fmt, ##__VA_ARGS__)
|
||||
#else
|
||||
#define rsc_dbg(fmt, ...)
|
||||
#define rsc_dbg(fmt, ...)
|
||||
#endif
|
||||
|
||||
#define CHECK_SUC() do { if (!suc) return false; } while (0)
|
||||
|
||||
/**
|
||||
* Initialize the repository. Mark all resources as claimed by PLATFORM.
|
||||
*/
|
||||
void rsc_init_registry(void);
|
||||
|
||||
/**
|
||||
* Claim a GPIO using port name and pin number.
|
||||
*
|
||||
* @param unit - claiming unit
|
||||
* @param port_name - port (eg. 'A')
|
||||
* @param pin - pin number 0-15
|
||||
* @return success
|
||||
*/
|
||||
error_t rsc_claim_pin(Unit *unit, char port_name, uint8_t pin);
|
||||
|
||||
/**
|
||||
* Claim a resource by the Resource enum
|
||||
*
|
||||
* @param unit - claiming unit
|
||||
* @param rsc - resource to claim
|
||||
* @return success
|
||||
*/
|
||||
error_t rsc_claim(Unit *unit, Resource rsc);
|
||||
|
||||
/**
|
||||
* Claim a range of resources (use for resources of the same type, e.g. USART1-5)
|
||||
*
|
||||
* @param unit - claiming unit
|
||||
* @param rsc0 - first resource to claim
|
||||
* @param rsc1 - last resource to claim
|
||||
* @return success (E_SUCCESS = complete claim)
|
||||
*/
|
||||
error_t rsc_claim_range(Unit *unit, Resource rsc0, Resource rsc1);
|
||||
|
||||
/**
|
||||
* Claim GPIOs by bitmask and port name, atomically.
|
||||
* Tear down the unit on failure.
|
||||
@@ -29,20 +66,57 @@ error_t rsc_claim_range(Unit *unit, Resource rsc0, Resource rsc1);
|
||||
* @param unit - claiming unit
|
||||
* @param port_name - port (eg. 'A')
|
||||
* @param pins - pins, bitmask
|
||||
* @return success
|
||||
* @return success (E_SUCCESS = complete claim)
|
||||
*/
|
||||
error_t rsc_claim_gpios(Unit *unit, char port_name, uint16_t pins);
|
||||
|
||||
/**
|
||||
* Release all resources held by a unit, de-init held GPIOs
|
||||
*
|
||||
* @param unit - unit to tear down
|
||||
*/
|
||||
void rsc_teardown(Unit *unit);
|
||||
|
||||
/**
|
||||
* Release a resource by the Resource enum
|
||||
*
|
||||
* @param unit - holding unit, NULL to ignore
|
||||
* @param rsc - resource to release
|
||||
*/
|
||||
void rsc_free(Unit *unit, Resource rsc);
|
||||
|
||||
/**
|
||||
* Release a range of resources (use for resources of the same type, e.g. USART1-5)
|
||||
*
|
||||
* @param unit - releasing unit
|
||||
* @param rsc0 - first resource to release
|
||||
* @param rsc1 - last resource to release
|
||||
*/
|
||||
void rsc_free_range(Unit *unit, Resource rsc0, Resource rsc1);
|
||||
|
||||
/**
|
||||
* Get name of a resource by the Resource enum.
|
||||
* Uses a static buffer, DO NOT store the returned pointer.
|
||||
*
|
||||
* @param rsc - resource to inspect
|
||||
* @return resource name (eg. PA1)
|
||||
*/
|
||||
const char * rsc_get_name(Resource rsc);
|
||||
|
||||
/** Get rsc owner name */
|
||||
/**
|
||||
* Get rsc owner name
|
||||
*
|
||||
* @param rsc - resource to inspect
|
||||
* @return name of the holding unit, or "NULL" (string)
|
||||
*/
|
||||
const char * rsc_get_owner_name(Resource rsc);
|
||||
|
||||
/** Print all available resource names */
|
||||
/**
|
||||
* Print all available resource names
|
||||
* (this is the pins part of the PINOUT.TXT file)
|
||||
*
|
||||
* @param iw - writer to use
|
||||
*/
|
||||
void rsc_print_all_available(IniWriter *iw);
|
||||
|
||||
#endif //GEX_RESOURCES_H
|
||||
|
||||
Reference in New Issue
Block a user