fm_rules.c File Reference

The places the bench keeps, the write gate and the kinds of entries (fm_rules.h). More...

#include "fm_rules.h"
#include <string.h>
#include "card_tree.h"
#include "kst_store.h"
#include "log_name.h"

Macros
#define	JOURNAL_TXT   KST_STORE_RECORD ".TXT"
	The journal's name, KST.TXT, as the panel writes it.
#define	JOURNAL_NEW   KST_STORE_RECORD FM_NEW_SUFFIX
	The journal's name while it is written, KST.NEW.
#define	HITEC_TXT   "HITEC.TXT"
	The Hitec programmer's record, HITEC.TXT (HITEC_CARD_RECORD of hitec_card.h, which this layer does not include).
#define	HITEC_NEW   "HITEC" FM_NEW_SUFFIX
	The Hitec record's name while it is written, HITEC.NEW.

Functions
static int	fold_at (const char *s, size_t i)
	Byte i of s with case folded as FatFs compares long names: ff_wtoupper() (ffunicode.c, ESP-IDF v5.5.5) maps a to z onto A to Z, and its Latin-1 blocks U+00E0 to U+00F6 and U+00F8 to U+00FE (shift -32) map ä ö ü onto Ä Ö Ü. ß (U+00DF) is in neither block and stays ß. The UTF-8 forms of the three pairs differ in their second byte alone (C3 A4 / C3 84), so the fold keeps the length of every string.
static bool	same_folded (const char *a, const char *b)
	Whether two strings are one with case folded as FatFs folds it (fold_at()).
static bool	ends_in (const char *name, const char *suffix)
	Whether name ends in suffix, case folded, after at least one character.
bool	fm_op_writes (fm_op_t op)
	Whether op writes to the card.
bool	fm_logging (const log_marks_t *marks)
	Whether a log file is open: any of the logger's three marks.
fm_err_t	fm_gate (fm_op_t op, const fm_bench_t *bench)
	The write gate: whether the bench's state lets op run.
fm_err_t	fm_path_err (fm_path_t r)
	The answer of a path call (fm_name.h) as the core's.
bool	fm_same_path (const char *a, const char *b)
	Whether two paths name one place, case folded.
bool	fm_path_within (const char *outer, const char *inner)
	Whether path inner is outer or a place below it, case folded.
static bool	fixed_dir (const fm_bench_t *bench, const char *path)
	Whether folder path is one of the bench's or a log folder, or stands above one.
fm_place_t	fm_place_of (const fm_bench_t *bench, const char *dir, const char *name, bool is_dir)
	Where name in folder dir stands.
bool	fm_busy (const fm_bench_t *bench, const char *dir, const char *name)
	Whether the logger writes name in folder dir now (log_marks_busy()).
static fm_err_t	fault_allows (const fm_bench_t *bench, fm_op_t op)
	What the fault log's place lets op do.
fm_err_t	fm_allowed (const fm_bench_t *bench, fm_op_t op, const char *dir, const char *name, bool is_dir)
	Whether op may run on name in folder dir: the gate, the file's place and whether the logger writes it, in that order.
fm_err_t	fm_target_check (const fm_bench_t *bench, const char *dir, const char *name, bool typed)
	Whether a COPY, a SAVE, a RENAME or a NEW may make name in folder dir.
fm_kind_t	fm_kind_of (const char *dir, const char *name, bool is_dir)
	The kind of name in folder dir.
bool	fm_read_at_start (const char *dir, const char *name)
	Whether a file saved as name in dir is read only at the next start of the panel: an ESC profile.

Variables
static const char *const	k_bench_dirs []
	The bench's deepest folders: each of them and every folder above it is FIXED (card_tree.h).
static const char *const	k_fault []
	The fault log's three names (fault_log.h).

Detailed Description

The places the bench keeps, the write gate and the kinds of entries (fm_rules.h).

SPDX-License-Identifier: MIT

Function Documentation

ends_in()

bool ends_in ( const char * name, const char * suffix )

static

Whether name ends in suffix, case folded, after at least one character.

Parameters

name	a name
suffix	".csv", ".txt" or ".json"

Returns

true for "RUN.CSV" and "run.csv"; false for ".csv" alone

fault_allows()

fm_err_t fault_allows ( const fm_bench_t * bench, fm_op_t op )

static

What the fault log's place lets op do.

FatFs runs without its file lock (CONFIG_FATFS_FS_LOCK 0) and removes a file the logger has open for its append; the append then writes into clusters the removal freed. A copy or a delete waits while the logger may write a line: the link down, or a line queued or under way. The delete itself runs under the logger's lock as well (firmware/panel/main/panel_files.c).

Parameters

bench	the bench; may be NULL
op	the operation

Returns

FM_OK, FM_ERR_BUSY while a line may be written, or FM_ERR_FIXED

fixed_dir()

bool fixed_dir ( const fm_bench_t * bench, const char * path )

static

Whether folder path is one of the bench's or a log folder, or stands above one.

Parameters

bench	the log folders in force; may be NULL
path	the folder's path

Returns

true for a FIXED folder

fm_allowed()

fm_err_t fm_allowed	(	const fm_bench_t *	bench,
		fm_op_t	op,
		const char *	dir,
		const char *	name,
		bool	is_dir )

Whether op may run on name in folder dir: the gate, the file's place and whether the logger writes it, in that order.

Parameters

bench	the bench; may be NULL
op	the operation
dir	the folder, a path from the root
name	the entry's name
is_dir	the entry is a folder

Returns

FM_OK; FM_ERR_ARMED or FM_ERR_LOGGING for a write the gate stops; FM_ERR_BUSY for a file the logger writes, and for the fault log's COPY and DELETE while the link is down; FM_ERR_FIXED, FM_ERR_LOCKED for the places; FM_ERR_ARG for COPY, EDIT or SAVE of a folder and NEW in a file

fm_busy()

bool fm_busy	(	const fm_bench_t *	bench,
		const char *	dir,
		const char *	name )

Whether the logger writes name in folder dir now (log_marks_busy()).

Parameters

bench	the open files; NULL is none
dir	the folder
name	the file's name

Returns

true for a busy file

fm_gate()

fm_err_t fm_gate	(	fm_op_t	op,
		const fm_bench_t *	bench )

The write gate: whether the bench's state lets op run.

Reads pass in every state. A write is refused while the bench is ARMED, and while a log file is open; ARMED is the answer when both hold.

Parameters

op	the operation
bench	the bench; NULL is SAFE with nothing open

Returns

FM_OK, FM_ERR_ARMED or FM_ERR_LOGGING

fm_kind_of()

fm_kind_t fm_kind_of	(	const char *	dir,
		const char *	name,
		bool	is_dir )

The kind of name in folder dir.

Parameters

dir	the folder, a path from the root
name	the entry's name
is_dir	the entry is a folder

Returns

its kind

fm_logging()

bool fm_logging

(

const log_marks_t *

marks

)

Whether a log file is open: any of the logger's three marks.

Parameters

marks

the open files; NULL is none

Returns

true while a run, a test's CSV or a report is open

fm_op_writes()

bool fm_op_writes

(

fm_op_t

op

)

Whether op writes to the card.

Parameters

op	the operation

Returns

true for COPY, MOVE, RENAME, DELETE, NEW and SAVE

fm_path_err()

fm_err_t fm_path_err

(

fm_path_t

r

)

The answer of a path call (fm_name.h) as the core's.

Parameters

r	what fm_path_join() or fm_path_check() said

Returns

FM_OK; FM_ERR_ARG for FM_PATH_ARG; FM_ERR_NAME for a path that is bad, too long or too deep

fm_path_within()

bool fm_path_within	(	const char *	outer,
		const char *	inner )

Whether path inner is outer or a place below it, case folded.

Parameters

outer	a folder's path
inner	a path

Returns

true when inner is in outer or is outer

fm_place_of()

fm_place_t fm_place_of	(	const fm_bench_t *	bench,
		const char *	dir,
		const char *	name,
		bool	is_dir )

Where name in folder dir stands.

Parameters

bench	the log folders in force; may be NULL
dir	the folder, a path from the root
name	the entry's name
is_dir	the entry is a folder

Returns

its place

fm_read_at_start()

bool fm_read_at_start	(	const char *	dir,
		const char *	name )

Whether a file saved as name in dir is read only at the next start of the panel: an ESC profile.

Parameters

dir	the folder
name	the file's name

Returns

true for a ".json" in BENCH/ESC/CONF

fm_same_path()

bool fm_same_path	(	const char *	a,
		const char *	b )

Whether two paths name one place, case folded.

Parameters

a	a path
b	a path

Returns

true for one place

fm_target_check()

fm_err_t fm_target_check	(	const fm_bench_t *	bench,
		const char *	dir,
		const char *	name,
		bool	typed )

Whether a COPY, a SAVE, a RENAME or a NEW may make name in folder dir.

A name a person types (typed: RENAME, NEW) follows fm_name_check(). A name a copy or a save carries over from the card is any name of 1 to FM_NAME_MAX bytes without "/" that is not "." or "..": it may hold any character a computer wrote, and only its ".NEW" has to stay listed (fm_name_new()). Either way neither the name nor its ".NEW" is a LOCKED or FAULT name (a file named KST in BENCH/KST/CONF would write the programmer's KST.NEW), and the paths of both fit fm_path_join().

Parameters

bench	the log folders in force; may be NULL
dir	the target folder
name	the name to make
typed	the name is typed by a person

Returns

FM_OK, FM_ERR_LOCKED, FM_ERR_FIXED, FM_ERR_NAME or FM_ERR_ARG

fold_at()

int fold_at ( const char * s, size_t i )

static

Byte i of s with case folded as FatFs compares long names: ff_wtoupper() (ffunicode.c, ESP-IDF v5.5.5) maps a to z onto A to Z, and its Latin-1 blocks U+00E0 to U+00F6 and U+00F8 to U+00FE (shift -32) map ä ö ü onto Ä Ö Ü. ß (U+00DF) is in neither block and stays ß. The UTF-8 forms of the three pairs differ in their second byte alone (C3 A4 / C3 84), so the fold keeps the length of every string.

Parameters

s	a UTF-8 string
i	a byte offset in it

Returns

the byte as compared

same_folded()

bool same_folded ( const char * a, const char * b )

static

Whether two strings are one with case folded as FatFs folds it (fold_at()).

Parameters

a	a string
b	a string

Returns

true when they are one

Variable Documentation

k_bench_dirs

const char* const k_bench_dirs[]

static

Initial value:

                                     = {
    CARD_AUTO_LOGS, CARD_USER_LOGS, CARD_ESC_CONF, CARD_KST_CONF,
    CARD_HITEC_CONF,
}

The bench's deepest folders: each of them and every folder above it is FIXED (card_tree.h).

k_fault

const char* const k_fault[]

static

Initial value:

                                = {
    CARD_FAULT_LOG, CARD_FAULT_OLD, CARD_FAULT_TMP,
}

The fault log's three names (fault_log.h).