gex/gex-core
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Doc comments and explanations

Browse Source
This commit is contained in:
MightyPork
2018-01-24 22:09:42 +01:00
parent 052fa4ce08
commit 8e9c653090
9 changed files with 115 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
comm/messages.h
+8 -1
View File
@@ -1,6 +1,12 @@
//
// Created by MightyPork on 2017/11/21.
//
// This is the only file to include from the comm/ folder directly.
// Provides TinyFrame message types, utilities for forming payloads,
// bulk read and write routines.
//
// See the other headers in the folder for prototypes.
//
#ifndef GEX_MESSAGES_H
#define GEX_MESSAGES_H
@@ -36,9 +42,10 @@ enum Message_Types_ {
MSG_PERSIST_CFG = 0x23, //!< Write current settings to Flash (the equivalent of replacing the lock jumper)
};
/** The shared USB-serial TinyFrame instance */
extern TinyFrame *comm;
// Must be after the enum because it's used in the header file.
// those must be after the enum because it's used in the header files
#include "msg_responses.h"
#include "msg_bulkread.h"
#include "msg_bulkwrite.h"
comm/msg_bulkread.c
+1 -1
View File
@@ -68,7 +68,7 @@ close:
return TF_CLOSE;
}
/** Start the bulk read flow */
void bulkread_start(TinyFrame *tf, BulkRead *bulk)
{
assert_param(bulk);
comm/msg_bulkread.h
+2
View File
@@ -1,6 +1,8 @@
//
// Created by MightyPork on 2017/12/23.
//
// Bulk read (providing data for bulk read by the PC)
//
#ifndef GEX_F072_MSG_BULKREAD_H
#define GEX_F072_MSG_BULKREAD_H
comm/msg_bulkwrite.c
+1 -1
View File
@@ -62,7 +62,7 @@ close:
return TF_CLOSE;
}
/** Start the bulk write flow */
void bulkwrite_start(TinyFrame *tf, BulkWrite *bulk)
{
assert_param(bulk);
comm/msg_bulkwrite.h
+6
View File
@@ -1,10 +1,16 @@
//
// Created by MightyPork on 2017/12/23.
//
// Bulk write (receiving bulk write from the PC)
//
#ifndef GEX_F072_MSG_BULKWRITE_H
#define GEX_F072_MSG_BULKWRITE_H
#ifndef GEX_MESSAGES_H
#error "Include messages.h instead!"
#endif
#include <TinyFrame.h>
typedef struct bulk_write BulkWrite;
comm/msg_responses.c
+2
View File
@@ -38,6 +38,7 @@ void com_respond_ok(TF_ID frame_id)
com_respond_buf(frame_id, MSG_SUCCESS, NULL, 0);
}
void com_send_pb(TF_TYPE type, PayloadBuilder *pb)
{
uint32_t len;
@@ -45,6 +46,7 @@ void com_send_pb(TF_TYPE type, PayloadBuilder *pb)
com_send_buf(type, buf, len);
}
void com_send_buf(TF_TYPE type, const uint8_t *buf, uint32_t len)
{
TF_Msg msg;
comm/msg_responses.h
+2
View File
@@ -1,6 +1,8 @@
//
// Created by MightyPork on 2017/12/22.
//
// Routines for sending TinyFrame responses.
//
#ifndef GEX_F072_MSG_RESPONSES_H
#define GEX_F072_MSG_RESPONSES_H
framework/resources.c
+12 -39
View File
@@ -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;
framework/resources.h
+81 -7
View File
@@ -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