Embedded/elua
1
0
Fork 0
mirror of https://github.com/elua/elua.git synced 2025-01-08 20:56:17 +08:00
Code Issues Projects Releases Wiki Activity

working on the reference manual

Browse Source
This commit is contained in:
James Snyder 2009-06-29 16:43:17 +00:00
parent af944cc8bc
commit 240644ffbf
10 changed files with 459 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/build_dist_doc.sh
View File

@ -39,6 +39,7 @@ then
for lang in en pt
do
rm -f $lang/arch_platform_*.html
rm -f $lang/refman_gen_*.html
done
rm -f index_*.html wb/wb_usr.lua ssSearch*.html wb_bar_*.html
rm -f wb_search*.txt wb_title*.html wb_tree*.html

27
doc/builddoc.lua
View File

@ -7,7 +7,7 @@ local doc_sections = { "arch_platform", "refman_gen" }
local components =
{
arch_platform = { "ll", "pio", "spi", "uart", "timers", "pwm", "cpu", "eth" },
refman_gen = { "cpu" }
refman_gen = { "bit", "pd", "cpu", "pack" }
}
-- List here all languages for the documentation (make sure to keep English ("en") the first one)
@ -40,6 +40,8 @@ end
- the string "eLua" becomes <b>eLua</b>
- strings between two tildas (~~) get special code-like formatting
- newlines are changed to ' ' if 'keepnl' isn't true
- '&' is translated to its corresponding HTML code.
- '<<' and '>>" are also translated to the corresponding HTML codes (note the repetition).
--]]
local function format_string( str, keepnl )
-- replace double "special chars" with "temps" for later use
@ -49,23 +51,36 @@ local function format_string( str, keepnl )
str = str:gsub( "%^%^", "\004" )
str = str:gsub( "~~", "\005" )
-- Translate 'special' HTML chars to their equivalents
local tr_table =
{
[ "%&" ] = "&amp;",
}
for char, rep in pairs( tr_table ) do
str = str:gsub( char, rep )
end
-- some double chars are replaced directly with their HTML codes
str = str:gsub( "<<", "&lt;" )
str = str:gsub( ">>", "&gt;" )
-- replace eLua with <b>eLua</b>
str = str:gsub( "eLua", "<b>eLua</b>" )
-- $string$ becomes <b>string></b>
str = str:gsub( "%$([^%s][^%$]+)%$", "<b>%1</b>" )
str = str:gsub( "%$([^%s%$][^%$]*)%$", "<b>%1</b>" )
-- %string% becomes <i>string</i>
str = str:gsub( "%%([^%s][^%%]+)%%", "<i>%1</i>" )
str = str:gsub( "%%([^%s%%][^%%]*)%%", "<i>%1</i>" )
-- @ref@text@ becomes <a href="ref">text</a>
str = str:gsub( "@([^%s][^@]+)@([^%s][^@]+)@", '<a href="%1">%2</a>' )
str = str:gsub( "@([^%s@][^@]*)@([^%s@][^@]*)@", '<a href="%1">%2</a>' )
-- ^ref^text^ becomes <a target="_blank" href="ref">text</a>
str = str:gsub( "%^([^%s][^%^]+)%^([^%s][^%^]+)%^", '<a target="_blank" href="%1">%2</a>' )
str = str:gsub( "%^([^%s%^][^%^]*)%^([^%s%^][^%^]*)%^", '<a target="_blank" href="%1">%2</a>' )
-- strings between two tildas (~~) get special code-like formatting
str = str:gsub( "~([^%s][^~]+)~", function( x )
str = str:gsub( "~([^%s~][^~]*)~", function( x )
x = x:gsub( "\n", "<br>" )
x = x:gsub( "%s%s+", function( x ) return ( "&nbsp;" ):rep( #x ) end )
return "<p><code>" .. x .. "</code></p>"

11
doc/en/refman_gen.html Normal file
View File

@ -0,0 +1,11 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="Content-Language" content="en-us"><title>eLua reference manual - generic modules</title>
<link rel="stylesheet" type="text/css" href="../style.css"></head>
<body style="background-color: rgb(255, 255, 255);">
<h3>Reference manual - generic modules</h3>
<p>This part of the reference manual presents the generic modules in <b>eLua</b> (see <a href="refman.html">here</a> for more information about generic
modules).</p>
</body></html>

2
doc/en/tut_bootstick.html
View File

@ -36,7 +36,7 @@ Your call.</strong></p>
<h2>Prerequisites</h2>
<p>To have your own bootable eLua USB stick you'll need:
<p>To have your own bootable <b>eLua</b> USB stick you'll need:
<ul><li>an USB stick. I tested this on an 128M USB stick, because
it's the smallest I could find. You should be OK with a 4M stick or

2
doc/luadoc/arch_platform_eth.lua
View File

@ -18,7 +18,7 @@ data_en =
incoming packets) and a timer interrupt (timers are used internally by uIP). However, the uIP main loop is only called from the Ethernet interrupt handler
in eLua, so in order to acknowledge the timer interrupt (as well as to provide some optimizations) a function that "forces" an Ethernet interrupt
must also be provided by the platform interface (see @#platform_eth_force_interrupt@here@ for details).</p>
<p>To put everything together, part of the Ethernet platform interface for the $m3s$ platform is given below:</p>
<p>To put everything together, part of the Ethernet platform interface for the $lm3s$ platform is given below:</p>
~u32 platform_eth_get_elapsed_time()
{
if( eth_timer_fired )

145
doc/luadoc/refman_gen_bit.lua Normal file
View File

@ -0,0 +1,145 @@
-- eLua reference manual - bit module
data_en =
{
-- Title
title = "eLua reference manual - bit module",
-- Menu name
menu_name = "bit",
-- Overview
overview = [[Since Lua doesn't have built-in capabilities for bit operations, the $bit$ module was added to eLua to fill this gap. It is based on the ^http://luaforge.net/projects/bitlib^bitlib^
library written by Reuben Thomas (slightly adapted to eLua) and provides basic bit operations (like setting and clearing bits) and bitwise operations.]],
-- Functions
funcs =
{
{ sig = "number = #bit.bit#( position )",
desc = "Generate a number with a 1 bit (used for mask generation). Equivalent to %1 <<<< position% in C.",
args =
{
{ name = "position", desc = "position of the bit that will be set to 1." },
},
ret = "$number$ - a number with only one 1 bit at $position$ (the rest are set to 0."
},
{ sig = "flag = #bit.isset#( value, position )",
desc = "Test if a given bit is set.",
args =
{
{ name = "value", desc = "the value to test." },
{ name = "position", desc = "bit position to test." }
},
ret = "$flag$ - 1 if the bit at the given position is 1, 0 otherwise."
},
{ sig = "flag = #bit.isclear#( value, position )",
desc = "Test if a given bit is cleared.",
args =
{
{ name = "value", desc = "the value to test." },
{ name = "position", desc = "bit position to test." }
},
ret = "$flag$ - 1 if the bit at the given position is 0, 0 othewise."
},
{ sig = "number = #bit.set#( value, pos1, pos2, ..., posn )",
desc = "Set bits in a number.",
args =
{
{ name = "value", desc = "the base number." },
{ name = "pos1", desc = "position of the first bit to set." },
{ name = "pos2", desc = "position of the second bit to set." },
{ name = "posn", desc = "position of the nth bit to set." }
},
ret = "$number$ - the number with the bit(s) set in the given position(s)."
},
{ sig = "number = #bit.clear#( value, pos1, pos2, ..., posn )",
desc = "Clear bits in a number.",
args =
{
{ name = "value", desc = "the base number." },
{ name = "pos1", desc = "position of the first bit to clear." },
{ name = "pos2", desc = "position of the second bit to clear." },
{ name = "posn", desc = "position of thet nth bit to clear." },
},
ret = "$number$ - the number with the bit(s) cleared in the given position(s)."
},
{ sig = "number = #bit.bnot#( value )",
desc = "Bitwise negation, equivalent to %~~value% in C.",
args =
{
{ name = "value", desc = "the number to negate." },
},
ret = "$number$ - the bitwise negated value of the number.",
},
{ sig = "number = #bit.band#( val1, val2, ... valn )",
desc = "Bitwise AND, equivalent to %val1 & val2 & ... & valn% in C.",
args =
{
{ name = "val1", desc = "first AND argument." },
{ name = "val2", desc = "second AND argument." },
{ name = "valn", desc = "nth AND argument." },
},
ret = "$number$ - the bitwise AND of all the arguments."
},
{ sig = "number = #bit.bor#( val1, val2, ... valn )",
desc = "Bitwise OR, equivalent to %val1 | val2 | ... | valn% in C.",
args =
{
{ name = "val1", desc = "first OR argument." },
{ name = "val2", desc = "second OR argument." },
{ name = "valn", desc = "nth OR argument." }
},
ret = "$number$ - the bitwise OR of all the arguments."
},
{ sig = "number = #bit.bxor#( val1, val2, ... valn )",
desc = "Bitwise exclusive OR (XOR), equivalent to %val1 ^^ val2 ^^ ... ^^ valn% in C.",
args =
{
{ name = "val1", desc = "first XOR argument." },
{ name = "val2", desc = "second XOR argument." },
{ name = "valn", desc = "nth XOR argument." }
},
ret = "$number$ - the bitwise exclusive OR of all the arguments."
},
{ sig = "number = #bit.lshift#( value, shift )",
desc = "Left-shift a number, equivalent to %value << shift% in C.",
args =
{
{ name = "value", desc = "the value to shift." },
{ name = "shift", desc = "positions to shift." },
},
ret = "$number$ - the number shifted left",
},
{ sig = "number = #bit.rshift#( value, shift )",
desc = "Logical right shift a number, equivalent to %( unsigned )value >>>> shift% in C.",
args =
{
{ name = "value", desc = "the value to shift." },
{ name = "shift", desc = "positions to shift." },
},
ret = "$number$ - the number shifted right (logically)."
},
{ sig = "number = #bit.arshift#( value, shift )",
desc = "Arithmetic right shift a number equivalent to %value >>>> shift% in C.",
args =
{
{ name = "value", desc = "the value to shift." },
{ name = "shift", desc = "positions to shift." }
},
ret = "$number$ - the number shifted right (arithmetically)."
}
}
}

109
doc/luadoc/refman_gen_cpu.lua Normal file
View File

@ -0,0 +1,109 @@
-- eLua reference manual - CPU module
data_en =
{
-- Title
title = "eLua reference manual - CPU module",
-- Menu name
menu_name = "cpu",
-- Overview
overview = [[This module deals with low-level access to CPU (and related modules) functionality, such as reading and writing memory, or
enabling and disabling interrupts. It also offers access to platform specific CPU-related constants using a special macro defined in the
platform's $platform_conf.h$ file, as exaplained @#cpu_constants@here@.]],
-- Data structures, constants and types
structures =
{
{ text = [[cpu.INT_GPIOA
cpu.INT_GPIOB
.............
cpu.INT_UDMA]],
name = "CPU constants",
desc = [[eLua has a mechanism that lets the user export an unlimited number of constants to the $cpu$ module. Although in theory any kind of constant can be exposed by this module,
one should only use constants related to the CPU and its subsystems (as shown above, where a number of CPU specific interrupt masks are exposed to Lua using this mechanism). To use this
mechanism, just declare the $PLATFORM_CPU_CONSTANTS$ macro in your platform's $platform_conf.h$ file and list all your constants as part of this macro, each enclosed in a special macro called
$_C$. For example, to get the constants listed above declare your $PLATFORM_CPU_CONSTANTS$ macro like this:</p>
~#define PLATFORM_CPU_CONSTANTS\
_C( INT_GPIOA ),\
_C( INT_GPIOB ),\
.................
_C( INT_UDMA )~<p>
<p>It's worth to note that adding more constants does not increas RAM usage, only Flash usage, so you can expose as much constants as you need without worrying about RAM consumption.]]
},
},
-- Functions
funcs =
{
{ sig = "#cpu.w32#( address, data )",
desc = "Writes a 32-bit word to memory.",
args =
{
{ name = "address", desc = "the memory address." },
{ name = "data", desc = "the 32-bit data to write." }
},
},
{ sig = "data = #cpu.r32#( address )",
desc = "Read a 32-bit word from memory.",
args =
{
{ name = "address", desc = "the memory address." }
},
ret = "$data$ - the 32-bit word read from memory."
},
{ sig = "#cpu.w16#( address, data )",
desc = "Writes a 16-bit word to memory.",
args =
{
{ name = "address", desc = "the memory address." },
{ name = "data", desc = "the 16-bit data to write." }
},
},
{ sig = "data = #cpu.r16#( address )",
desc = "Reads a 16-bit word from memory.",
args =
{
{ name = "address", desc = "the memory address." }
},
ret = "$data$ - the 16-bit word read from memory."
},
{ sig = "#cpu.w8#( address, data )",
desc = "Writes a byte to memory.",
args =
{
{ name = "address", desc = "the memory address." },
{ name = "data", desc = "the byte to write." }
}
},
{ sig = "data = #cpu.r8#( address )",
desc = "Reads a byte from memory.",
args =
{
{ name = "address", desc = "the memory address" }
},
ret = "$data$ - the byte read from memory."
},
{ sig = "#cpu.cli#()",
desc = "Disable CPU interrupts."
},
{ sig = "#cpu.sei#()",
desc = "Enable CPU interrupts."
},
{ sig = "clock = #cpu.clock#()",
desc = "Get the CPU core frequency.",
ret = "$clock$ - the CPU clock (in Hertz)."
}
},
}

135
doc/luadoc/refman_gen_pack.lua Normal file
View File

@ -0,0 +1,135 @@
-- eLua reference manual - pack
data_en =
{
-- Title
title = "eLua reference manual - pack",
-- Menu name
menu_name = "pack",
-- Overview
overview = [[This module allows for arbitrary packing of data into Lua strings and unpacking data from Lua strings. In this way, a string can be used to store data in a platform-indepdendent
manner. It is based on the ^http://www.tecgraf.puc-rio.br/~~lhf/ftp/lua/#lpack^lpack^ module from Luiz Henrique de Figueiredo (with some minor tweaks). </p>
<p>Both methods of this module (@#pack@pack@ and @#unpack@unpack@) use a $format string$ to describe how to pack/unpack the data. The format string contains one or more $data specifiers$, each
data specifier is applied to a single variable that must be packed/unpacked. The data specifier has the following general format:</p>
~[endianness]<<format specifier>>[count]~
<p>where:
<ul>
<li>$endianness$ is an optional endian flags that specifies how the numbers that are to be packed/unpacked are stored in memory. It can be either:
<ol>
<li>$'<<'$ for little endian.</li>
<li>$'>>'$ for big endian.</li>
<li>$'='$ for native endian (the platform's endian order, default).</li>
</ol></li>
<li>$format specifier$ describes what kind of variable will be packed/unpacked. $The format specifier is case-sensitive$. The possible values of this parameter are summarized in the table below:
<p><table class="table_center">
<tbody>
<tr>
<th>Format specifier</th>
<th>Corresponding variable type</th>
</tr>
<tr>
<td>'z'</td>
<td>zero-terminated string</td>
</tr>
<tr>
<td>'p' </td>
<td>string preceded by length byte</td>
</tr>
<tr>
<td>'P' </td>
<td>string preceded by length word</td>
</tr>
<tr>
<td>'a' </td>
<td>string preceded by length size_t</td>
</tr>
<tr>
<td>'A' </td>
<td>string</td>
</tr>
<tr>
<td>'f' </td>
<td>float</td>
</tr>
<tr>
<td>'d' </td>
<td>double</td>
</tr>
<tr>
<td>'n' </td>
<td>Lua number</td>
</tr>
<tr>
<td>'c' </td>
<td>char</td>
</tr>
<tr>
<td>'b' </td>
<td>byte = unsigned char</td>
</tr>
<tr>
<td>'h' </td>
<td>short</td>
</tr>
<tr>
<td>'H' </td>
<td>unsigned short</td>
</tr>
<tr>
<td>'i' </td>
<td>int</td>
</tr>
<tr>
<td>'I' </td>
<td>unsigned int</td>
</tr>
<tr>
<td>'l' </td>
<td>long</td>
</tr>
<tr>
<td>'L' </td>
<td>unsigned long</td>
</tr>
</table><br></p></li>
<li>$count$ is an optional counter for the $format specifier$. For example, $i5$ instructs the code to pack/unpack 5 integer variables, as opposed to $i$ that specifies a
single integer variable.</li>
</ul></p>]],
-- Functions
funcs =
{
{ sig = "packed = #pack.pack#( format, val1, val2, ..., valn )",
desc = "Packs variables in a string.",
args =
{
{ name = "format", desc = "format specifier (as described @#overview@here@)." },
{ name = "val1", desc = "first variable to pack." },
{ name = "val2", desc = "second variable to pack." },
{ name = "valn", desc = "nth variable to pack." },
},
ret = "$packed$ - a string containing the packed representation of all variables according to the format."
},
{ sig = "nextpos, val1, val2, ..., valn = #pack.unpack#( string, format, [ init ] )",
desc = "Unpacks a string",
args =
{
{ name = "string", desc = "the string to unpack." },
{ name = "format", desc = "format specifier (as described @#overview@here@)." },
{ name = "init", desc = "$(optional)$ marks where in $string$ the unpacking should start (1 if not specified)." }
},
ret =
{
"$nextpos$ - the position in the string after unpacking.",
"$val1$ - the first unpacked value.",
"$val2$ - the second unpacked value.",
"$valn$ - the nth unpacked value."
}
}
},
}

34
doc/luadoc/refman_gen_pd.lua Normal file
View File

@ -0,0 +1,34 @@
-- eLua reference manual - platform data
data_en =
{
-- Title
title = "eLua reference manual - platform data",
-- Menu name
menu_name = "Platform data (pd)",
-- Overview
overview = [[This module contains functions that access specific platform data. Useful if the code needs to know on which platform it runs.]],
-- Functions
funcs =
{
{ sig = "platform = #pd.platform#()",
desc = "Get platform name.",
ret = "$platform$ - the name of the platform on which eLua is running.",
},
{ sig = "cpu = #pd.cpu#()",
desc = "Get CPU name.",
ret = "$cpu$ - the name of the CPU of the platform on which eLua is running.",
},
{ sig = "board = #pd.board#()",
desc = "Get board name.",
ret = "$board$ - the name of the board on which eLua is running.",
}
},
}

2
doc/wb/wb_usr_template.lua
View File

@ -362,7 +362,7 @@ wb_usr.tree =
name = { en = "Generic Modules", pt = "Módulos Genéricos" },
link = "refman_gen.html",
folder = {
$$REFMAN_GEN$$,
$$REFMAN_GEN$$
},
},
{