Show
Ignore:
Timestamp:
08/06/08 14:29:39 (5 months ago)
Author:
liamstask
Message:

- add examples to system doc

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • firmware/trunk/core/makingthings/system.c

    r748 r790  
    6262  @param state An integer specifying the state system 
    6363  @return Zero on success. 
     64   
     65  \b Example 
     66  \code 
     67  // enable the System subsystem 
     68  System_SetActive(1); 
     69  \endcode 
    6470*/ 
    6571int System_SetActive( int state ) 
    … …  
    95101  Returns the active state of the subsystem. 
    96102  @return The active state of the subsystem - 1 (active) or 0 (inactive). 
     103   
     104  \b Example 
     105  \code 
     106  if(System_GetActive()) 
     107  { 
     108    // System is active 
     109  } 
     110  else 
     111  { 
     112    // System is inactive 
     113  } 
     114  \endcode 
    97115*/ 
    98116int System_GetActive( ) 
    … …  
    103121/** 
    104122  Returns the free size of the heap. 
     123  The heap size is set in config.h in the constant CONTROLLER_HEAPSIZE. 
     124  Any calls to Malloc will take their memory from the heap.  This allows 
     125  you to check how much heap is remaining. 
    105126  @return The size free memory. 
     127   
     128  \b Example 
     129  \code 
     130  // see how much memory is available 
     131  int freemem = System_GetFreeMemory(); 
     132  \endcode 
    106133*/ 
    107134int System_GetFreeMemory( void ) 
    … …  
    111138 
    112139/** 
    113   Gets the board's Serial Number.   
     140  Gets the board's Serial Number. 
     141  Each board has a serial number, although it's not necessarily unique 
     142  as you can reset it as you please. 
     143   
     144  The serial number is used to determine the Ethernet MAC address, so boards 
     145  on the same network need to have unique serial numbers. 
    114146  @return CONTROLLER_OK ( = 0 ). 
     147   
     148  \b Example 
     149  \code 
     150  // get this board's serial number 
     151  int sernum = System_GetSerialNumber(); 
     152  \endcode 
    115153*/ 
    116154int System_GetSerialNumber( void ) 
    … …  
    123161 
    124162/** 
    125   Sets the Serial Number. Note that this can be changed by the user at  
     163  Sets the Serial Number.  
     164  Note that this can be changed by the user at  
    126165  any time, but that it is used in the \ref Network subsystem to form the last  
    127166  two bytes of the network MAC address, so ideally units on the same network 
    128167  should have unique serial numbers. 
    129   @return CONTROLLER_OK if OK. 
     168  @return 0 on success. 
     169   
     170  \b Example 
     171  \code 
     172  // set the serial number to 12345 
     173  System_SetSerialNumber(12345); 
     174  \endcode 
    130175*/ 
    131176int System_SetSerialNumber( int serial ) 
    … …  
    137182/** 
    138183  Returns the board to SAM-BA mode, erasing the flash memory. 
    139   Leaves the board in a non-deterministic state awaiting a power cycle or reset. 
    140   @return CONTROLLER_OK if OK. 
     184  When a board is in SAM-BA mode, it is ready to have new firmware uploaded to it. 
     185  Note that you'll need to unplug/replug the board to complete the transition to 
     186  SAM-BA mode. 
     187  @param sure Confirm you're sure you want to do this. 
     188  @return 0 on success. 
     189   
     190  \b Example 
     191  \code 
     192  // prepare to be uploaded 
     193  System_SetSamba(1); 
     194  \endcode 
    141195*/ 
    142196int System_SetSamba( int sure ) 
    … …  
    168222/** 
    169223  Gives the board a name. 
    170   The name must be alpha-numeric - only letters and numbers. 
     224  The name must be alpha-numeric - only letters and numbers.  It can help you 
     225  determine one board from another when there are more than one connected to  
     226  your system. 
    171227  @param name A string specifying the board's name 
    172   @return CONTROLLER_OK if OK. 
     228  @return 0 on success. 
     229   
     230  \b Example 
     231  \code 
     232  // give the board a special name 
     233  System_SetName("my very special controller"); 
     234  \endcode 
    173235*/ 
    174236int System_SetName( char* name ) 
    … …  
    193255  Read the board's name. 
    194256  @return The board's name as a string. 
     257   
     258  \b Example 
     259  \code 
     260  char* board_name = System_GetName(); 
     261  \endcode 
    195262*/ 
    196263char* System_GetName( ) 
    … …  
    234301  Will reboot the board if the parameter sure is true. 
    235302  @param sure confirms the request is true. 
    236   @return CONTROLLER_OK if OK. 
     303  @return 0 on success. 
     304   
     305  \b Example 
     306  \code 
     307  // reboot 
     308  System_SetReset(1); 
     309  \endcode 
    237310*/ 
    238311int System_SetReset( int sure )