[Tinyos-contrib-commits]
CVS: tinyos-1.x/contrib/wustl/websites/agilla/docs/tutorials
10_add_instr.html, NONE, 1.1 OPfindMatch.nc, NONE,
1.1 OPfindMatchM.nc, NONE, 1.1
Chien-Liang Fok
chien-liang at users.sourceforge.net
Wed May 3 14:18:01 PDT 2006
Update of /cvsroot/tinyos/tinyos-1.x/contrib/wustl/websites/agilla/docs/tutorials
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16969
Added Files:
10_add_instr.html OPfindMatch.nc OPfindMatchM.nc
Log Message:
--- NEW FILE: 10_add_instr.html ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><!-- InstanceBegin template="/Templates/Main.dwt" codeOutsideHTMLIsLocked="false" -->
<head>
<!-- InstanceBeginEditable name="doctitle" -->
<title>Agilla</title>
<!-- InstanceEndEditable -->
<link rel="stylesheet" href="../../styles.css" type="text/css" />
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<!-- InstanceBeginEditable name="head" -->
<!-- InstanceEndEditable -->
</head>
<body>
<!-- InstanceBeginEditable name="MainText" -->
<h1>Lesson 10: Adding Custom Instructions to Agilla</h1>
<p><em>Last Updated on
<!-- #BeginDate format:Am1a -->May 3, 2006 4:17 PM<!-- #EndDate -->
.</em></p>
<p>Adding new instructions to Agilla is not difficult. This tutorial describes
the process.</p>
<p>For this example, we will create a new instruction, <code>findmatch</code>, that takes
a variable as a parameter, and searches through the heap to find an equivalent
variable. If it finds a match, it stores the index on the opstack and sets
the condition code equal to 1, otherwise it sets the condition code equal to
1.</p>
<p>The built-in Agilla instructions are located in <code><agilla>/opcodes</code>. All
instructions must provide interface BytecodeI, which is located in <code><agilla>/interfaces/BytecodeI.nc</code>.
ByteCodeI defines a single command:</p>
<pre class="screen">command result_t execute(uint8_t instr, AgillaAgentContext* context);</pre>
<p>This command is called when the instruction is executed.
It is passed the instruction's byte code to allow a single component to implement
multiple instructions. It is also passed the context of the agent that executed
the instruction. </p>
<p>Usually, an instruction is implemented using a configuration and a module.
Here is the implementation of findmatch:</p>
<p><a href="OPfindMatch.nc">Configuration</a>:</p>
<pre class="screen">configuration OPfindMatch{<br> provides interface BytecodeI;<br>}<br>implementation {<br> components OPfindMatchM, OpStackC, TupleUtilC, ErrorMgrProxy; <br> BytecodeI = OPfindMatchM; <br> OPfindMatchM.OpStackI -> OpStackC;<br> OPfindMatchM.TupleUtilI -> TupleUtilC;<br> OPfindMatchM.Error -> ErrorMgrProxy; <br>}</pre>
<p><a href="OPfindMatchM.nc">Module</a>:</p>
<pre class="screen">includes Agilla;
/**
* Searches through the heap to find the index of a matching variable.
*/
module OPfindMatchM {
provides interface BytecodeI;
uses {
interface OpStackI;
interface TupleUtilI; // For comparing variables
interface ErrorMgrI as Error;
}
}
implementation {
command result_t BytecodeI.execute(uint8_t instr,
AgillaAgentContext* context)
{
AgillaVariable arg; // the variable to search for
dbg(DBG_USR1, "VM (%i:%i): Executing findMatch\n",
context->id.id, context->pc-1);
if (call OpStackI.popOperand(context, &arg))
{
int16_t i;
for (i = 0; i < AGILLA_HEAP_SIZE; i++)
{
if (context->heap.pos[i].vtype != AGILLA_TYPE_INVALID)
{
if (call TupleUtilI.fEquals(&arg, &context->heap.pos[i]))
{
call OpStackI.pushValue(context, i); // save index on stack
context->condition = 1; // indicate match found
return SUCCESS;
}
}
}
context->condition = 0; // indicate no match found
return SUCCESS;
} else
return FAIL;
}
}</pre>
<p>Next choose a bytecode for your instruction. Open <Agilla>/AgillaOpcodes.h.
This file contains enumerations of all instructions in Agilla. The main enumeration
is BasicInstruction. These are the primary instructions in Agilla that are
listed
<a href="../../isa.html">here</a>. Since all of the bytecodes in the Basic
instruction set are used, Agilla provides 13 extended instruction sets, each
of which can
contain an additional 256 instructions. In this case, we will assign findmatch
bytecode 0x1c within enumeration ExtendedISA1.</p>
<pre class="screen">typedef enum {
...
IOPfindMatch = 0x1c,
...
} ExtendedISA1;</pre>
<p>Now open <Agilla>/Agilla.nc and wire the opcode to AgillaEngineC.</p>
<pre class="screen">implementation {
...
components OPfindMatch;
...
AgillaEngineC.ExtendedISA1[IOPfindMatch] -> OPfindMatch;
...
}</pre>
<p>You now have to recompile and install the Agilla firmware on the motes.
</p>
<p>The final step is to modify the AgentInjector to recognize the new instruction.
Go into edu.wustl.mobilab.agilla.opcodes and open the opcode class that the
new instruction is part of (in this case ExtendedOpcodes1.java). Add the following
line to it:</p>
<pre class="screen">public static final short OPfindMatch = 0x1c;</pre>
<p>This specifies the instruction and its opcode to the Agilla assembler. </p>
<p>If the instruction contains embedded operands, you need to specify the number
operands and the number of bits dedicated
to it using:</p>
<pre class="screen">public static final int ArgNumOP<opcode> = <num operands>;
public static final int ArgNumOP<opcode> = <num bits>; </pre>
<p>Sometimes instructions have predefined arguments. For example, you can <code>pushc
photo</code>. To specify this, create a two-dimensional array where each row
contains the argument and its corresponding value. For example, the specification
for pushc is as follows:</p>
<pre class="screen"> public static final String[][] ArgValOPpushc = new String[][] {
{"temperature", "1"},
{"temp", "1"},
{"photo", "2"},
{"mic", "3"},
{"microphone", "3"},
{"magx", "4"},
{"magnetometerx", "4"},
{"magy", "5"},
{"magnetometery", "5"},
{"accelx", "6"},
{"accelerometerx", "6"},
{"accely", "7"},
{"accelerometery", "7"},
// the following are for changing an agent's description
{"unknown", "3"},
{"unspecified","0"},
{"cargo","1"},
{"fire","2"}
};</pre>
<p> </p>
<!-- InstanceEndEditable -->
<hr>This work is supported by the <a href="http://formal.cs.uiuc.edu/contessa">ONR MURI Project CONTESSA</a>
and the <a href="http://www.nsf.gov/">NSF</a> under grant number CCR-9970939.
</body>
<!-- InstanceEnd --></html>
--- NEW FILE: OPfindMatch.nc ---
// $Id: OPfindMatch.nc,v 1.1 2006/05/03 21:17:59 chien-liang Exp $
/* Agilla - A middleware for wireless sensor networks.
* Copyright (C) 2004, Washington University in Saint Louis
* By Chien-Liang Fok.
*
* Washington University states that Agilla is free software;
* you can redistribute it and/or modify it under the terms of
* the current version of the GNU Lesser General Public License
* as published by the Free Software Foundation.
*
* Agilla is distributed in the hope that it will be useful, but
* THERE ARE NO WARRANTIES, WHETHER ORAL OR WRITTEN, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
* MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE.
*
* YOU UNDERSTAND THAT AGILLA IS PROVIDED "AS IS" FOR WHICH NO
* WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. THERE ARE NO
* WARRANTIES AND NO REPRESENTATION THAT AGILLA IS FREE OF
* INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER
* PROPRIETARY RIGHTS. THERE ARE NO WARRANTIES THAT SOFTWARE IS
* FREE FROM "BUGS", "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS",
* OR OTHER HARMFUL CODE.
*
* YOU ASSUME THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR
* ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF
* INFORMATION GENERATED USING SOFTWARE. By using Agilla you agree to
* indemnify, defend, and hold harmless WU, its employees, officers and
* agents from any and all claims, costs, or liabilities, including
* attorneys fees and court costs at both the trial and appellate levels
* for any loss, damage, or injury caused by your actions or actions of
* your officers, servants, agents or third parties acting on behalf or
* under authorization from you, as a result of using Agilla.
*
* See the GNU Lesser General Public License for more details, which can
* be found here: http://www.gnu.org/copyleft/lesser.html
*/
/* tab:4
*
*
* "Copyright (c) 2000-2002 The Regents of the University of California.
* All rights reserved.
*
* Permission to use, copy, modify, and distribute this software and
* its documentation for any purpose, without fee, and without written
* agreement is hereby granted, provided that the above copyright
* notice, the following two paragraphs and the author appear in all
* copies of this software.
*
* IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY
* PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
* DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
* DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
* INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
* PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
* CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT,
* UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
*
*/
/* tab:4
*
* IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
* By downloading, copying, installing or using the software you
* agree to this license. If you do not agree to this license, do
* not download, install, copy or use the software.
*
* Intel Open Source License
*
* Copyright (c) 2002 Intel Corporation
* All rights reserved.
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* Neither the name of the Intel Corporation nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INTEL OR ITS
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
*
*/
/*
* Authors: Chien-Liang Fok
* History: May 3, 2006 Inception.
*
*/
/**
* @author Chien-Liang Fok
*/
configuration OPfindMatch{
provides interface BytecodeI;
}
implementation {
components OPfindMatchM, OpStackC, TupleUtilC, ErrorMgrProxy;
BytecodeI = OPfindMatchM;
OPfindMatchM.OpStackI -> OpStackC;
OPfindMatchM.TupleUtilI -> TupleUtilC;
OPfindMatchM.Error -> ErrorMgrProxy;
}
--- NEW FILE: OPfindMatchM.nc ---
// $Id: OPfindMatchM.nc,v 1.1 2006/05/03 21:17:59 chien-liang Exp $
/* Agilla - A middleware for wireless sensor networks.
* Copyright (C) 2004, Washington University in Saint Louis
* By Chien-Liang Fok.
*
* Washington University states that Agilla is free software;
* you can redistribute it and/or modify it under the terms of
* the current version of the GNU Lesser General Public License
* as published by the Free Software Foundation.
*
* Agilla is distributed in the hope that it will be useful, but
* THERE ARE NO WARRANTIES, WHETHER ORAL OR WRITTEN, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
* MERCHANTABILITY OR FITNESS FOR A PARTICULAR USE.
*
* YOU UNDERSTAND THAT AGILLA IS PROVIDED "AS IS" FOR WHICH NO
* WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. THERE ARE NO
* WARRANTIES AND NO REPRESENTATION THAT AGILLA IS FREE OF
* INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER
* PROPRIETARY RIGHTS. THERE ARE NO WARRANTIES THAT SOFTWARE IS
* FREE FROM "BUGS", "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS",
* OR OTHER HARMFUL CODE.
*
* YOU ASSUME THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR
* ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF
* INFORMATION GENERATED USING SOFTWARE. By using Agilla you agree to
* indemnify, defend, and hold harmless WU, its employees, officers and
* agents from any and all claims, costs, or liabilities, including
* attorneys fees and court costs at both the trial and appellate levels
* for any loss, damage, or injury caused by your actions or actions of
* your officers, servants, agents or third parties acting on behalf or
* under authorization from you, as a result of using Agilla.
*
* See the GNU Lesser General Public License for more details, which can
* be found here: http://www.gnu.org/copyleft/lesser.html
*/
/* tab:4
*
*
* "Copyright (c) 2000-2002 The Regents of the University of California.
* All rights reserved.
*
* Permission to use, copy, modify, and distribute this software and
* its documentation for any purpose, without fee, and without written
* agreement is hereby granted, provided that the above copyright
* notice, the following two paragraphs and the author appear in all
* copies of this software.
*
* IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY
* PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
* DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS
* DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
* THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
* INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
* MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
* PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
* CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT,
* UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
*
*/
/* tab:4
*
* IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
* By downloading, copying, installing or using the software you
* agree to this license. If you do not agree to this license, do
* not download, install, copy or use the software.
*
* Intel Open Source License
*
* Copyright (c) 2002 Intel Corporation
* All rights reserved.
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are
* met:
*
* Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* Neither the name of the Intel Corporation nor the names of its
* contributors may be used to endorse or promote products derived from
* this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE INTEL OR ITS
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*
*
*/
/**
* @author Chien-Liang Fok <liangfok at wustl.edu>
*/
includes Agilla;
/**
* Searches through the heap to find the index of a matching variable.
*/
module OPfindMatchM {
provides interface BytecodeI;
uses {
interface OpStackI;
interface TupleUtilI; // For comparing variables
interface ErrorMgrI as Error;
}
}
implementation {
command result_t BytecodeI.execute(uint8_t instr, AgillaAgentContext* context) {
AgillaVariable arg; // the variable to search for
dbg(DBG_USR1, "VM (%i:%i): Executing findMatch\n", context->id.id, context->pc-1);
if (call OpStackI.popOperand(context, &arg))
{
int16_t i;
for (i = 0; i < AGILLA_HEAP_SIZE; i++)
{
if (context->heap.pos[i].vtype != AGILLA_TYPE_INVALID)
{
if (call TupleUtilI.fEquals(&arg, &context->heap.pos[i]))
{
call OpStackI.pushValue(context, i); // save index on stack
context->condition = 1; // indicate match found
return SUCCESS;
}
}
}
context->condition = 0; // indicate no match found
return SUCCESS;
} else
return FAIL;
}
}
More information about the Tinyos-contrib-commits
mailing list