dnl (c)INRIA 2000 Christophe Lavarenne
dnl $Id: syndex.m4x,v 1.1 2000/04/17 13:03:01 lavarenn Exp $
divert(-1)
# SynDEx v5 generic executive macros definitions (executive generator),
# relying on processor-specific or media-specific macros,
# see <type>.m4x for macros specific to processor or media type <type>.

##################
# ERROR MANAGEMENT

# ------
# error_(msg) displays error message with file and line error location
define(`error_',`errprint(__file__:__line__: m4: `$1'
)')

ifdef(`__gnu__',,`dnl GNU m4 predefines the `__gnu__' macro
error_(`this file must be processed by GNU m4 (REQUIRED!)')m4exit(1)')

ifdef(  __file__`_already_included',`error_(`already included')m4exit(1)',
`define(__file__`_already_included')')

# ------------
# unsupported_(macroName) for TARGET LANGUAGE DEPENDENT macros
define(`unsupported_',`def(`$1',`error_(``$1' macro is not supported')')')


##########
# COMMENTS
# Portable, target language independent, comments must be enclosed
# between `comment{' and `}comment', they may include any characters,
# including unbalanced quotes, but included braces must be balanced, as in:
# `comment{Comments with {balanced} curly braces}comment'
# This generates target language dependent comments from the macros
# `comment' and `comment_', which are TARGET LANGUAGE DEPENDENT.

# -------
# comment{}comment  C-style multi-line comments:
define(`comment',`pushdef(`comment',`changequote)`'popdef(`comment')')changequote({,})comment_(')
define(`comment_', `changequote({,}){/* $1 */}changequote')

# Shell-style till-end-of-line comments:
# The TARGET LANGUAGE DEPENDENT start-comment character (# for As) is given
# as 3rd argument of the patsubst macro in the following definition:
#define(`comment_',`changequote({,})patsubst({{$1}},{^},{# })changequote')
#define(`comment',`pushdef(`comment',`changequote)`'popdef(`comment')
#dnl')changequote({,})comment_(')

# -----------
# _(codeline)
# ALL TARGET PROCESSOR DEPENDENT CODE IS GENERATED WITH THE MACRO `_'
# ALL OTHER DEPENDENCIES ARE DULY ANNOTATED WITH `TARGET ... DEPENDENT'.
# _(codeline) generates a newline, indentation spaces, and codeline;
# use `indent_(+)' to increase by 2 the number of indentation spaces;
# use `indent_(-)' to decrease by 2 the number of indentation spaces;
# use `define(`NOindent')' to make the next `_' generate only codeline.
define(`_',`ifdef(`NOindent',`undefine(`NOindent')',`
indentString')$@')
define(`indentString')
define(`indent_',`ifelse(
$1,+,`pushdef(`indentString', indentString`  ')',
$1,-,`popdef(`indentString')ifdef(`indentString',,`define(`indentString')'dnl
`error_(`more `indent_(-)' than `indent_(+)'')')',
`error_(`expected `+' or `-' as argument for `indent_'')')')

# ------------------------
# def(macroName, macroDef)
# The `def' macro defines macros which are generated by SynDEx, they
# generate a trace of the macro call, unless the NOTRACEDEF macro is defined:
define(`def', `define(`$1', `ifdef(`NOTRACEDEF', `define(`NOindent')',
`comment{''changequote([,])[``$][0($][*)'']changequote``}comment`'')$2')')


##################
# SOURCE STRUCTURE
# The executive source is structured by pairs of macros which must be balanced
# (the second macro of a pair is named as the first, prefixed with `end').
# For example, the pair `processor_' and `endprocessor_' enclose all other
# macros (except maybe some header and footer comments).
# `pushtag' and `poptag' are used by macro pairs to check their balance,
# and to generate unique labels for control structures.

# -------
# pushtag(key) Open a new block structure with its own tagged key:
define(`tagnumber_',0) dnl block structure counter
define(`pushtag', `dnl
pushdef(`tag_',`$1_'tagnumber_)dnl push tagged key on tag stack
define(`tagnumber_',incr(tagnumber_))dnl next tagnumber
')

# ------
# poptag(key) Check block structure balance and pop tag stack if ok.
define(`poptag', `ifelse(index(tag_,$1),0,
`popdef(`tag_')', dnl if balanced, pop tag stack.
`ifdef(`tag_', dnl otherwise complain:
`error_(`Unbalanced control structure: expected end'tag_)',
`error_(`Unbalanced control structure: no previous '$1`_')')')')

# ----------
# processor_(1procrType,2procrName, 3appliName, 4versionStamp,5dateStamp)
# Very first macro generated at beginning of file
def(`processor_', `dnl *** versionStamp $4 SHOULD be checked
'define(`NOTRACEDEF')`undefine(`NOTRACEDEF')undefine(`NOindent')dnl
define(`processorType_', $1)define(`processorName_', $2)dnl
include($1.m4x)dnl SynDEx executive macros customization for processor type $1
comment{$4, $5, application $3, processor $2 type=$1}comment
undivert`'dnl to allow $1.m4x to generate something after the previous comment
sinclude($3.m4x)dnl application specific macros, file MAY not exist
sinclude($2.m4x)dnl processor specific macros, file MAY not exist
pushtag(`processor')')

# -------------
# endprocessor_() Very last macro generated before the end of file
def(`endprocessor_',`poptag(`processor')checkTagBalance')
define(`checkTagBalance',`ifdef(`tag_', `dnl
error_(`Uncomplete control structure: missing end'tag_)dnl
popdef(`tag_')checkTagBalance')')


############
# DATA TYPES
# Data types are used to check buffers access consistency, and to convert
# buffers sizes, specified in type units, into memory address units.
# `typedef_' defines a new type with its size in address units:

# --------
# typedef_(typeName,typeSize)
def(`typedef_', `ifelse($#,2,`ifdef(`$1_size_',
`error_(`WARNING: type $1 redefined')')`'define(`$1_size_',$2)',
`error_(`Expected arguments: typeName, typeSizeInAddressUnits')')')

# The macro-executive specific to the target processor MUST `typedef_'
# the `bool' type, that the executive generator uses for conditionning.
# It SHOULD also `typedef_' basic C-like types `char, int, float, double'.


###################
# MEMORY ALLOCATION
# `basicAlloc_' allocates and labels memory cells: TARGET LANGUAGE DEPENDENT
# `alloc_' compiles arguments for `basicAlloc_' unless
# `<type>_alloc_' if defined for type-specific memory allocations, or
# `<name>_alloc_' if defined for name-specific memory allocations (constants)
# `basicAlias_' relabels already allocated memory: TARGET LANGUAGE DEPENDENT
# `alias_' compiles arguments for `basicAlias_'
# The type and size of a label created by `alloc_' and `alias_' are stored
# as `<label>_type_' and `<label>_size_' for other macros to retrieve them.

# ------
# alloc_(1type,2newLabel[,3size[,4memBank]]) generated for each data-dependence
def(`alloc_',`dnl Check that newLabel is new:
ifdef(`$2_type_',  `error_(`$2 redeclared')')define(`$2_type_', $1)dnl
ifdef(`$1_size_',, `error_(`Undeclared data type: $1 for $2')')dnl
define(`$2_size_', ifelse($3,,1,$3))dnl use specific allocation macro:
ifdef(`$2_alloc_', `$2_alloc_', `dnl
ifdef(`$1_alloc_', `$1_alloc_', `basicAlloc_')')($2,$4)')
# -----------------
# <dataName>_alloc_(newLabel,memoryBank) APPLICATION SPECIFIC
# -----------------
# <dataType>_alloc_(newLabel,memoryBank) TARGET LANGUAGE DEPENDENT
# -----------
# basicAlloc_(newLabel,memoryBank) TARGET LANGUAGE DEPENDENT

#---------
# defined_(label) cheks that label has been defined by `alloc_'
define(`defined_', `ifdef(`$1_type_',,`error_(`Undeclared data buffer: $1')')')
# -----
# type_(label) returns the type with which label was defined by `alloc_'
define(`type_', `ifdef($1`_type_',$1_type_,`undefined')') dnl Get buffer type.

# ------
# alias_(newLabel,oldLabel[,offset=0[,size=oldLabel_size_-offset]]) generated
def(`alias_',`defined_($2)dnl Check that oldLabel exists.
define(`$1_type_',type_($2))dnl Declare new label with same type.
define(`$1_size_',ifelse(dnl newLabel size depends on arguments:
$#,2, `$2_size_', dnl offset=0 and same size by default.
$#,3, `ifelse(eval($3<$2_size_),1, `eval($2_size_-$3)',
      dnl offset given: size=oldLabelSize-offset by default.
      `error_(`arg3=offset=$3 >= $2'`_size_='$2_size_)')',
$#,4, `ifelse(eval($3+$4<=$2_size_),1, `eval($4)',
      dnl offset and size given: check that newLabel is within oldLabel.
      `error_(`arg3+arg4=offset+size=$3+$4 > $2'`_size_='$2_size_)')',
`error_(`Expected arguments: newLabel,oldLabel[,offset[,size]]')'dnl
))dnl End of `$1_size_' definition.
basicAlias_($@)')
# -----------
# basicAlias_(newLabel,oldLabel[,offset=0]) TARGET LANGUAGE DEPENDENT


#######################
# MEMORY INITIALIZATION
# `zero_' clears memory cells; it is the only supported initialization macro;
# other initializations must be done by application specific user macros.

# -----
# zero_(destLabel)
# This default definition does no more than checking destLabel existence,
# because most systems initially clear uninitialized static data (.bss section)
# If it is not the case, redefine `zero_' to effectively clear memory cells.
define(`zero_',`defined_($1)')


##################
# MEMORY TRANSFERS
# `basicCopy_' copies memory cells: TARGET LANGUAGE DEPENDENT
# `copy_' compiles arguments for default `basicCopy_' or for a type-specific
# `<type>_copy_' if defined for type-specific memory transfers.
# `shift_' compiles arguments for `basicCopy_' for sliding delays/windows.

# -----
# copy_(dest,srce[,size=srce_size_]) generated when input&output must be copied
def(`copy_',`dnl Check that dest and srce labels exist:
defined_($1)defined_($2)dnl Check that they have the same type:
ifelse(type_($1),type_($2),,`error_(`Data type mismatch')')dnl
pushdef(`copysize',ifelse(dnl Check arguments:
$#,2, `ifelse(eval($1_size_<$2_size_),1,
  `error_(`dest '$1`_size_='$1_size_ < srce $2`_size_='$2_size_)',
  `eval($2_size_)')',
$#,3, `ifelse(
  eval($3>$1_size_),1, `error_(`arg3=$3 > $1'`_size_='$1_size_)',
  eval($3>$2_size_),1, `error_(`arg3=$3 > $2'`_size_='$2_size_)',
  `eval($3)')',
`error_(`Expected arguments: destLabel,srceLabel[,size]')'))dnl
dnl If type-specific copy-macro exists, call it with 3 args:
ifdef(type_($1)`_copy_', `type_($1)_copy_($1,$2,copysize)',
  `basicCopy_($1,$2,copysize)' dnl Otherwise, use basicCopy.
)`'popdef(`copysize')')
# ----------
# basicCopy_(destLabel,srceLabel,memSize) TARGET LANGUAGE DEPENDENT
# srce and dest may overlap, but you may rely on: destLabel<srceLabel

# ------
# shift_(memory,in)  for sliding windows/delays
def(`shift_', `dnl Check that memory and in labels exist:
defined_($1)defined_($2)dnl Check that they have the same type:
ifelse(type_($1),type_($2),,`error_(`Data type mismatch')')dnl
pushdef(`NOTRACEDEF')dnl
_(alias_($1_second, $1, $2_size_))dnl
_(copy_($1, $1_second))dnl
_(alias_($1_last, $1, eval($1_size_-$2_size_)))dnl
_(copy_($1_last, $2))dnl
popdef(`NOTRACEDEF')')


####################
# CONTROL STRUCTURES
# The `bool' type is used for conditionning:
# when considered as a boolean, 0 means false and anything else means true.
# The `MGC' macro is changed by the macros `main_ loop_ endloop_ endmain_' to
# define a Macro-Generation-Context for the external I/O macros.

# -----------
# booldefined(label) Check that label's type is bool
define(`booldefined', `ifelse(type_($1),`bool',,
`error_(`Type bool expected for $1 which is of type 'type_($1))')')

# ---
# if_(bool) expected to be forward balanced by else_ or endif_
def(`if_', `booldefined($1)pushtag(`if')dnl
basicIf_($1, tag_)`'indent_(+)')
# --------
# basicIf_(bool, tagforElseOrEndif) TARGET LANGUAGE DEPENDENT

# ------
# ifnot_(bool) expected to be forward balanced by else_ or endif_
def(`ifnot_', `booldefined($1)pushtag(`if')dnl
basicIfnot_($1, tag_)`'indent_(+)')
# -----------
# basicIfnot_(bool, tagForElseOrEndif) TARGET LANGUAGE DEPENDENT

# -----
# else_() expected balanced backward by if_ or ifnot_ and forward by endif_
def(`else_', `indent_(-)dnl
basicElse_(tag_, poptag(`if')pushtag(`if')tag_)`'indent_(+)')
# ----------
# basicElse_(tagFromIf, tagForEndif) TARGET LANGUAGE DEPENDENT

# ------
# endif_() expected to be balanced backward by if_ or ifnot_ or else_
def(`endif_', `indent_(-)dnl
basicEndif_(tag_)`'poptag(`if')')
# -----------
# basicEndif_(tagFromIfOrElse) TARGET LANGUAGE DEPENDENT

# -----
# loop_() expected to be balanced forward by endloop_
define(`INITepilogue', 10)
def(`loop_', `undivert(INITepilogue)`'dnl Shared initializations epilogue code is undiverted here.
pushtag(`loop')define(`MGC',`LOOP')dnl
basicLoop_(tag_)`'indent_(+)')
# ----------
# basicLoop_(tagForEndloop) TARGET LANGUAGE DEPENDENT

# --------
# endloop_() expected to be balanced backward by loop_
def(`endloop_', `indent_(-)define(`MGC',`END')dnl
basicEndloop_(tag_)`'poptag(`loop')')
# -------------
# basicEndloop_(tagFromLoop) TARGET LANGUAGE DEPENDENT

ifelse(`OBSOLETE MACROS:

# hmul_(bool, `bool,...', `bool,...')  OBSOLETE
def(`hmul_', `booldefined($1)$1[0]=(h_term_($2))&&(h_term_($3));')
# hadd_(bool, `bool,...', `bool,...')  OBSOLETE
def(`hadd_', `booldefined($1)$1[0]=(h_term_($2))||(h_term_($3));')
# macro `h_term_' shared by `hmul_' and `hadd_'
define(`h_term_', `booldefined($1)$1[0]ifelse($#,1,,``&&'h_term_(shift($@))')')

# count_(int [, [bool],rst [, [bool],top]])  OBSOLETE
def(`count_', `ifelse($#,1,,`
  if(ifelse($2,,,`$2[0]&&')$3[0])
    $1[0]=ifelse($5,,,`ifelse($4,,,`$4[0]&&')$5[0]?1:')0;
  else
  dnl')
  $1[0]++;')

')


###############
# SYNCHRONIZERS
# To synchronize main (priority=0) and communication sequences (priority=1).
# Some `unsupported_' macros have an (unused) example guideline definition.

# -----------
# semaphores_({semFull,semEmpty,})  TARGET LANGUAGE DEPENDENT
# allocate and initialize named semaphores
unsupported_(`semaphores_', `number_($*)dnl
_(volatile int sem_[$#]; /* each semaphore is initially null */)')
define(`number_',`ifelse($1,,,`
_(`#define' $1 decr($#))number_(shift($*))')')

# -----
# Pre0_(s) ; priority 1->0 precedence  TARGET LANGUAGE DEPENDENT
unsupported_(`Pre0_', `dnl
_(sem_[$1]=1; /* set semaphore $1 */)')

# -----
# Suc0_(s) ; priority 0<-1 precedence  TARGET LANGUAGE DEPENDENT
unsupported_(`Suc0_', `dnl
_(while(sem_[$1]==0); /* wait until semaphore $1 set by `Pre0_($1)' */)dnl
_(sem_[$1]=0; /* reset it. */)')

# -----
# Pre1_(s) ; priority 0->1 or 1->1 precedence  TARGET LANGUAGE DEPENDENT
unsupported_(`Pre1_', `dnl
_(call Suc_$1_; /* label Suc_$1_ defined by `Suc1_($1)'*/)')

# -----
# Suc1_(s) ; priority 1<-0 or 1<-1 precedence  TARGET LANGUAGE DEPENDENT
unsupported_(`Suc1_', `dnl
_(Suc_$1_: if((sem_[$1]^=1)!=0) returnFromCall; /* change semaphore $1 */)dnl
_(/* if null (2nd pass) continue; otherwise (1st pass) return. */)')


#########################
# COMMUNICATION sequences
# Hooks are provided for TARGET HARDWARE DEPENDENT customization macros:
# `thread_' includes <mediaType>.m4x if it exists, then calls:
#   `<mediaType>_shared_' if defined, for variables/subroutines/interrupts;
#   `basicThread_' to generate an entry label for the communication sequence;
#   `<mediaType>_ini_' if defined, for media configuration/initialization.
# `endthread_' calls `<mediaType>_end_' if defined, then `basicEndthread_'.
# `send_' calls `<mediaType>_send_'
# `recv_' calls `<mediaType>_recv_'
# `sync_' calls `<mediaType>_sync_'

# -------
# thread_(mediaType,mediaName {, procrName})
def(`thread_', `pushtag(`thread')dnl
pushdef(`mediaType_',$1)pushdef(`mediaName_',$2)dnl
pushdef(`threadArgs_',`$@')dnl
sinclude($1.m4x)dnl mediaType specific macros, MAY not exist.
sinclude($2.m4x)dnl mediaName specific macros, MAY not exist.
ifdef(mediaType_()`_shared_',`mediaType_()_shared_(shift($@))')
basicThread_(mediaName_)indent_(+)dnl
ifdef(mediaType_()`_ini_',`mediaType_()_ini_(shift($@))')')
# -------------------
# <mediaType>_shared_(mediaName,procrNames)  TARGET MEDIA DEPENDENT, OPTIONAL
# ----------------
# <mediaType>_ini_(mediaName,procrNames)  TARGET MEDIA DEPENDENT, OPTIONAL
# ------------
# basicThread_(mediaName) TARGET LANGUAGE DEPENDENT
# Example of specific definition for pseudo-C:
unsupported_(`basicThread_', `_(thread_$1_:)')

# ------
# lindex(key,list)
# may be useful for indexing a processor name in `thread_'s {,procrName} list
define(`lindex',`ifelse($2,$1,0, $2,,-100,
`incr(lindex($1,shift(shift($@))))')')

# ------------
# endthread_()
def(`endthread_', `dnl
ifdef(mediaType_()`_end_',`mediaType_()_end_(mediaName_,threadArgs_)')dnl
indent_(-)basicEndthread_(mediaName_)dnl
popdef(`threadArgs_')popdef(`mediaName_')popdef(`mediaType_')dnl
poptag(`thread')')
# ----------------
# <mediaType>_end_(mediaName,procrNames) TARGET MEDIA DEPENDENT
# ---------------
# basicEndthread_(mediaName)  TARGET LANGUAGE DEPENDENT
unsupported_(`basicEndthread_',`dnl
_(Pre0_($1`_end_'))dnl
_(returnFromCall; /* end of thread $1 */)')

# -----
# send_(bufferName, senderProcrType,senderProcrName {,receiverProcrName})
def(`send_',`defined_($1)dnl check $1 buffer existence
ifdef(`mediaType_',,     dnl check `send_' context
`error_(`Use `send_' between `thread_' and `endthread_'')')dnl
ifdef(mediaType_()`_send_',, dnl check `send_' substitution
`error_(mediaType_()`_send_ macro is undefined')')dnl
mediaType_()_send_($@)')
# -----------------
# <mediaType>_send_(bufferName,Procrs) TARGET MEDIA DEPENDENT

# -----
# recv_(bufferName, senderProcrType,senderProcrName {,receiverProcrName})
# the senderProcrType may be used to decide if byte-reversing is needed
def(`recv_',`defined_($1)dnl check $1 buffer existence
ifdef(`mediaType_',,     dnl check `recv_' context
`error_(`Use `recv_' between `thread_' and `endthread_'')')dnl
ifdef(mediaType_()`_recv_',, dnl check `recv_' substitution
`error_(mediaType_()`_recv_ macro is undefined')')dnl
mediaType_()_recv_($@)')
# -----------------
# <mediaType>_recv_(bufferName,Procrs) TARGET MEDIA DEPENDENT

# -----
# sync_(dataType,size, senderProcrType,senderProcrName {,receiverProcrName})
def(`sync_',`ifdef(`$1_size_',,`error_(`Undefined data type: $1')')dnl
ifdef(`mediaType_',, dnl check `sync_' context
`error_(`Use `sync_' between `thread_' and `endthread_'')')dnl
ifdef(mediaType_()`_sync_',, dnl check `sync_' substitution
`error_(mediaType_()`_sync_ macro is undefined')')dnl
mediaType_()_sync_($@)')
# -----------------
# <mediaType>_sync_(dataType,size,Procrs) TARGET MEDIA DEPENDENT

# --------------------------------------------------
# Forward-loader
# The distributed macroexecutive, generated by SynDEx on the host processor,
# must be compiled and downloaded on each processor before it may be executed.
# In an heterogeneous architecture, each processor may have its own way of
# booting after reset, from its own persistent memory (EPROM, FLASH, or disk).
# If the executable code is downloaded before runtime, in the boot memory of
# each processor, the code downloader is a matter of compilation process (see
# the syndex.m4m and <processorType>.m4m makefile generator files), and the
# macros <mediaType>_loadFrom_ and <mediatype>_loadDnto_ may be left undefined.
# Otherwise, the executable code of all processors is stored in the persistent
# memory of a single processor, named "root", and downloaded after each reset
# through the communication media of a coverage tree of the architecture graph,
# with the help not only of the boot-loader resident in the boot-memory of each
# processor, but also of the forward-loader part or each downloaded executable,
# generated by the <mediaType>_loadFrom_ and <mediaType>_loadDnto_ macros.
# The boot-loaders of different processor types may require executables to have
# different download structures, which are encapsulated, for the intermediate
# forward-loaders, into a common download structure, built at compile time,
# where each executable structure is simply preceeded by its 32-bits byte-size,
# received most significant byte first (big-endian).
# After macrosubstitution, compilation and linking, executables are structured
# for the boot-loader of their destination processor, encapsulated, stored, and
# later downloaded, in the order of a depth-first traversal of a coverage tree
# of the architecture graph, as encoded by the forward-loader macros loadFrom_
# and loadDnto_, and by the order of the macros spawn_thread_ (which initialize
# first the "loadFrom_" media towards root, then the other media in the order
# of their SynDEx declaration).

# ---------
# loadFrom_(procrName {,destMedia})
def(`loadFrom_', `ifdef(`mediaType_',, dnl check `loadFrom_' context
`error_(`Use `loadFrom_' between `thread_' and `endthread_'')')dnl
ifdef(mediaType_()`_loadFrom_', `mediaType_()_loadFrom_($@)')')
# ----------------------
# mediaType_()_loadFrom_(procrName {,destMedia}) MEDIA TYPE DEPENDENT, OPTIONAL

# ---------
# loadDnto_(srceMedia {,procrName})
def(`loadDnto_',`ifdef(`mediaType_',, dnl check `loadDnto_' context
`error_(`Use `loadDnto_' between `thread_' and `endthread_'')')dnl
ifdef(mediaType_()`_loadDnto_', `mediaType_()_loadDnto_($@)')')
# ----------------------
# mediaType_()_loadDnto_(srceMedia {,procrName}) MEDIA TYPE DEPENDENT, OPTIONAL

# --------------------------------------------------
# Backward-saver
# By symmetry with the "Forward-loader" described above, which in the initial
# phase transfers programs down the coverage tree of the archictecture graph,
# the "Backward-saver" in the final phase transfers data up the coverage tree
# and saves them in the mass memory of the root processor for later analysis.
# These data are usually runtime logs stored in the local memory of each pro-
# cessor to avoid communication overhead at runtime.

# ---------
# saveFrom_(srceMedia {,procrName})
def(`saveFrom_', `ifdef(`mediaType_',, dnl check `loadFrom_' context
`error_(`Use `saveFrom_' between `thread_' and `endthread_'')')dnl
ifdef(mediaType_()`_saveFrom_', `mediaType_()_saveFrom_($@)',
`error_(mediaType_()`_saveFrom_ macro is undefined')')')
# ----------------------
# mediaType_()_saveFrom_(srceMedia {,procrName}) MEDIA TYPE DEPENDENT, REQUIRED

# ---------
# saveUpto_(procrName {,destMedia})
def(`saveUpto_',`ifdef(`mediaType_',, dnl check `saveUpto_' context
`error_(`Use `saveUpto_' between `thread_' and `endthread_'')')dnl
ifdef(mediaType_()`_saveUpto_', `mediaType_()_saveUpto_($@)',
`error_(mediaType_()`_saveUpto_ macro is undefined')')')
# ----------------------
# mediaType_()_saveUpto_(procrName {,destMedia}) MEDIA TYPE DEPENDENT, REQUIRED


###############
# MAIN sequence

# -----
# main_ ; stratup entry point (after runtime boot)
def(`main_', `pushtag(`main')define(`MGC',`INIT')dnl
basicMain_()indent_(+)')
# ----------
# basicMain_() TARGET LANGUAGE DEPENDENT
# must declare "main" label for link with runtime boot

# --------
# endmain_ ; main return (to runtime shutdown)
def(`endmain_', `dnl
indent_(-)basicEndmain_()dnl
undefine(`MGC')poptag(`main')')
# -------------
# basicEndmain_() TARGET LANGUAGE DEPENDENT
# must return cleanly to runtime boot

# -------------
# spawn_thread_(mediaName)  TARGET LANGUAGE DEPENDENT
# Example of specific definition for pseudo-C:
unsupported_(`spawn_thread_', `_(call thread_$1_;)')

# ---------------
# wait_endthread_(mediaName)  TARGET LANGUAGE DEPENDENT
unsupported_(`wait_endthread_', `_(Suc0_($1`_end_'))')


##################
# Subroutine calls
# Generic macros for interfacing separately compiled C functions.

# ------
# Cdecl_(ret,label,args)  TARGET LANGUAGE DEPENDENT
# `Cdecl_' generates the declaration of a separately compiled C function:
# $1: return <type>
# $2: C function name
# $n>2: argument <type> (with `*' if passed by address)
# Example m4 declaration and corresponding generated C code:
# Cdecl_(int,my_fun,int,int*,float)
# | int my_fun(int, int*, float);

# ------
# Ccall_(ret,label,args)  TARGET LANGUAGE DEPENDENT
# `Ccall_' generates a call to a separately compiled C function,
# its interface mimics the ANSI C declaration of a function:
# $1: return <type> and <label>, or `void' if none
# $2: C function name (without the underscore prefix added by the assembler)
# $n>2: either `const' and <literal> for an integer literal argument, or
#       argument <type> (with `*' if passed by address) and <label>
# Example m4 declaration and macro-call with generated C code:
# def(`myfun', `Ccall_(int $3, my_fun, const 5, int *$1, float $2)')
# myfun(arg1,arg2,res) /* macro-call; generated code: */
# | res=myfun(5, arg1, arg2[0]);


#######################################
# Standard user logic/arithmetic macros
# Generic macros are defined for operations working similarly on several types.

define(`genLogic',`bool char int')
define(`genArith',`char int float double')
define(`genTypes',`bool char int float double')
define(`mustBe',`ifelse(index(`$2',$1),-1,
`error_(`This generic operation supports types $2, not type $1')')')

# Prototype regular expression:  \5: arg  \1: arg_type_  \3: arg_size_
define(`protoRE',`\(\w+\)\(\[\(\w+\)\]\)? *\(?\|!\|?!\)\(\w+\)')
define(`pType_',`type_($1)[$1_size_]')

# ------
# proto_(type?!name {,type?!name})
# prototype checker
define(`proto_',`ifelse($1,,,`dnl
pushdef(`typ_',patsubst($1,protoRE,`\1'))ifdef(typ_`_size_',,
`error_(`Undeclared data type: 'typ_)')dnl
pushdef(`siz_',patsubst($1,protoRE,`\3'))ifelse(siz_,,`define(`siz_',1)')dnl
pushdef(`arg_',patsubst($1,protoRE,`\5'))defined_(arg_)dnl
ifelse(pType_(arg_),typ_[siz_],,`error_(
`Expected type 'typ_[siz_]` for 'arg_` which is of type 'pType_(arg_))')dnl
popdef(`arg_')popdef(`siz_')popdef(`typ_')dnl
proto_(shift($@))')')

# generic unary operations for standard scalar and array types:
# ----
# gnot(logic[x]?1, logic[x]!2) # $2=~$1 TARGET LANGUAGE DEPENDENT
# ----
# gneg(arith[x]?1, arith[x]!2) # $2=-$1 TARGET LANGUAGE DEPENDENT

# generic binary operations for standard scalar and array types:
# ----
# gand(logic[x]?1, logic[x]?2, logic[x]!3) # $3=$1&$2 TARGET LANGUAGE DEPENDENT
# ----
#  gor(logic[x]?1, logic[x]?2, logic[x]!3) # $3=$1|$2 TARGET LANGUAGE DEPENDENT
# ----
# gxor(logic[x]?1, logic[x]?2, logic[x]!3) # $3=$1^$2 TARGET LANGUAGE DEPENDENT
# ----
# gadd(arith[x]?1, arith[x]?2, arith[x]!3) # $3=$1+$2 TARGET LANGUAGE DEPENDENT
# ----
# gsub(arith[x]?1, arith[x]?2, arith[x]!3) # $3=$1-$2 TARGET LANGUAGE DEPENDENT
# ----
# gmul(arith[x]?1, arith[x]?2, arith[x]!3) # $3=$1*$2 TARGET LANGUAGE DEPENDENT
# ----
# gdiv(arith[x]?1, arith[x]?2, arith[x]!3) # $3=$1/$2 TARGET LANGUAGE DEPENDENT

# generic relational operations for standard scalar types:
# ---------
#    gequal(types?i1, types?i2, bool!o) # $3=$1==$2 TARGET LANGUAGE DEPENDENT
# ---------
# gnotequal(types?i1, types?i2, bool!o) # $3=$1!=$2 TARGET LANGUAGE DEPENDENT
# ---------
#     gless(types?i1, types?i2, bool!o) # $3=$1<$2  TARGET LANGUAGE DEPENDENT
# ---------
#  gnotless(types?i1, types?i2, bool!o) # $3=$1>=$2 TARGET LANGUAGE DEPENDENT

divert`'dnl ---------------------- End of file -------------------------