next up previous
Next: MemStatistics Up: simlib Previous: MemManagerClass

MemoryAccess


     NAME
	  memoryaccess - Routines to access raw	memory

     DESCRIPTION
	  Routines to access values at raw memory locations in memory,
	  useful when interfacing to certain C-routines. Since these
	  routines acces memory	directly they should be	handled	with
	  care.	There are routines to access simple values, Texts
	  (strings) and	Arrays.

     EXAMPLE
	     external class MemoryAccess;
	     ref(MemoryAccess) Careful;
	     integer Adr,First,Next;
	     Careful:-new MemoryAccess;
	     Adr:=<some	C function returning an	Address>
	     First:=Careful.GetCIntAt(Adr,0);
	     Next:=Careful.GetCIntAt(Adr,4);

     AUTHOR
	  Boris	Magnusson, Lund	Institute of Technology.

     DETAILED INTERFACE
	     class MemoryAccess;
	  The operations in this class facilitates access to values by
	  machine  addresses,  typically  obtained  through calls to C
	  routines.  One situation where  it  is  interesting  to  use
	  these	 operations  is	 when  interfacing to a	C-routine that
	  return the address of	a C struct  (or	 a  C  array)  as  the
	  result.  The	operations  to fetch the values	can be used to
	  copy the entier struct (or array) to a corresponding	Simula
	  array. In this case one has to know the length of the	array,
	  often	defined	in C headerfiles.

	  The operations can also be used to fetch values  from	 a  C-
	  struct  one  by  one.	 In this case one has to know also the
	  offsets in the C-strucure for	each value.

	  The second set of operations can be used to  fill  in	 a  C-
	  structure  that  is  earlier	allocated  by C. This might be
	  useful  when	calling	 C-routines,  but  often  it  is  more
	  convenient  to  call	such  a	 routine with a	Simula integer
	  array, emulating the C-struct.

	  Supers: -
	  Kind:	Instantiable
	  Init:	none
	  Sequencing:
	   (GetCIntAt/GetCShortAt/GetCRealAt/GetCLongAt/
	    CArLength/CIntArray/CStringToText/CStringArToTextAr)*

	  (PutCIntAt/PutCShortAt/PutCRealAt/PutCLongAt/TextToCString/free)*
     OPERATIONS	TO FETCH VALUES	FROM C
     GetCIntAt
	     integer procedure GetCIntAt(CAddress,COffset);
	     integer CAddress; ! Base address ;
	     integer COffset;  ! Offset	from base in bytes, added to
	     CAddress.;
	  Return  the  integer	located	 at  'CAddress'+'COffset'.  If
	  CAddress  is	not  a legal address, this operation will most
	  likely crash the Simula program.

     GetCShortAt
	     integer procedure GetCShortAt(CAddress,COffset);
	     integer CAddress; ! Base address ;
	     integer COffset;  ! Offset	from base in bytes, added to
	     CAddress.;
	  Return the 16-bit integer located  at	 'CAddress'+'COffset'.
	  The  result  is sign-extended	to a propper integer value. If
	  CAddress is not a legal address, this	 operation  will  most
	  likely crash the Simula program.

     GetCRealAt
	     real procedure GetCRealAt(CAddress,COffset);
	     integer CAddress; ! Base address ;
	     integer COffset;  ! Offset	from base in bytes, added to
	     CAddress.;
	  Return   the	  floating    point    number	 located    at
	  'CAddress'+'COffset'.	  If  CAddress is not a	legal address,
	  this operation will most likely crash	the Simula program.

     GetCLongAt
	     long real procedure GetCLongAt(CAddress,COffset);
	     integer CAddress; ! Base address ;
	     integer COffset;  ! Offset	from base in bytes, added to
	     CAddress.;
	  Return the double precision floating point number located at
	  If CAddress is not a legal address, this operation will most
	  likely crash the Simula program.

     CArLength
	     integer procedure CArLength(CArray);
	     integer CArray;
	  Returns length of NULL-terminated array of Addresses	in  C.
	  successive  words until a zero word is found and returns the
	  count	of the non-zero	words.

     CIntArray
	     procedure CIntArray(CArray,CSize,IArray);
	     name IArray; ! result parameter;
	     integer CArray; ! Start of	C array	to copy	from;
	     integer CSize; ! Length of	C array	to copy;
	     integer array IArray; ! Simula array to copy to;
	  Copy 'CSize' integers	from  the  location  'CArray'  to  the
	  Simula  array	 IArray, starting at its first element.	If the
	  number of elements in	IArray is smaller than CSize, only the
	  first	part of	CArray is copied.

     CStringToText
	     procedure CStringToText(CString,TReturn);
	     name TReturn; ! Result parameter, becomes new Simula text
	     object.;
	     Integer CString; !	Address	of first byte in string	to
	     copy.;
	     Text TReturn; ! Returned as result;
	  Copy the content of memory at	 location  'CString'  until  a
	  NULL	byte  is found.	Place the copied bytes in a new	Simula
	  text returned	as 'TReturn'. This  procedure  creates	a  new
	  Simula  text and initializes it to the contet	of the CString
	  parameter.

     CStringArToTextAr
	     procedure	CStringArToTextAr(CArray,CSize,TArray);
	     name TArray; ! result parameter;
	     integer CArray; ! Start of	C array, to copy from;
	     integer CSize;  ! Size of C array ;
	     text array	TArray;	! Simula array to copy to;
	  Copy the C strings denoted by	'CArray' to new	 Simula	 texts
	  and  assign  to  Simula text array 'TArray'. Lowest index of
	  each array match. Copy at most  CSize	 strings  or,  if  the
	  Simula  array	 is shorter, only as many as to	fill 'TArray'.
	  For each string bytes	 are  copied  up  to  the  first  NULL
	  character.  Each  Simula  text  is  allocated	 to match this
	  length.

     OPERATIONS	TO STORE VALUES	IN C
     PutCIntAt
	     procedure PutCIntAt(CInt,CAddress,COffset);
	     integer CInt; ! Integer to	store;
	     integer CAddress; ! Base address ;
	     integer COffset;  ! Offset	from base in bytes, added to
	     CAddress.;
	  Store	the integer 'CInt' at  location	 'CAddress'+'COffset'.
	  If CAddress is not a legal address, this operation will most
	  likely crash the Simula program.

     PutCShortAt
	     procedure PutCShortAt(CShort,CAddress,COffset);
	     integer CShort; ! A 16-bit	integer	to store;
	     integer CAddress; ! Base address ;
	     integer COffset;  ! Offset	from base in bytes, added to
	     CAddress.;
	  Store	  the	16-bit	 integer    'CShort'	at    location
	  'CAddress'+'COffset'.	 If  CAddress  is not a	legal address,
	  this operation will most likely crash	the Simula program.

     PutCRealAt
	     procedure PutCRealAt(CReal,CAddress,COffset);
	     real CReal; ! real	(C-float) value	to store;
	     integer CAddress; ! Base address ;
	     integer COffset;  ! Offset	from base in bytes, added to
	     CAddress.;
	  Store	 the  floating	point  number  'CReal'	 at   location
	  'CAddress'+'COffset'.	  If  CAddress is not a	legal address,
	  this operation will most likely crash	the Simula program.

     PutCLongAt
	     procedure PutCLongAt(CLong,CAddress,COffset);
	     long real CLong; !	Long real (C-double) value to store;
	     integer CAddress; ! Base address ;
	     integer COffset;  ! Offset	from base in bytes, added to
	     CAddress.;
	  Store	the double precision floating point number 'CLong'  at
	  location  'CAddress'+'COffset'.   If CAddress	is not a legal
	  address, this	operation will most likely  crash  the	Simula
	  program.

     TextToCString
	     integer procedure TextToCString(SText);
	     name SText; ! (Adr	of text-box);
	     text SText; ! Simula text to copy;
	  Copy the content of 'SText',	NULL  terminated,  to  an  new
	  memory area allocated	in C address spece. Return the address
	  of the C string copy as an integer. Note  that  this	string
	  needs	 to be freed when no longer in use by a	call to	'free'
	  either by the	Simula program,	or by the C program  (but  not
	  both).

     free
	     procedure free(CAdr);
	     integer CAdr; ! memory area to free.;
	  Call the C utility 'free' to release a  memory  area	earler
	  obtained by a	call to	'malloc'.