/*
 *  Copyright (c) 1996-2007 Digi International Inc., All Rights Reserved
 *
 *  This software contains proprietary and confidential information of Digi
 *  International Inc.  By accepting transfer of this copy, Recipient agrees
 *  to retain this software in confidence, to prevent disclosure to others,
 *  and to make no use of this software other than that for which it was
 *  delivered.  This is an unpublished copyrighted work of Digi International
 *  Inc.  Except as permitted by federal law, 17 USC 117, copying is strictly
 *  prohibited.
 *
 *  Restricted Rights Legend
 *
 *  Use, duplication, or disclosure by the Government is subject to
 *  restrictions set forth in sub-paragraph (c)(1)(ii) of The Rights in
 *  Technical Data and Computer Software clause at DFARS 252.227-7031 or
 *  subparagraphs (c)(1) and (2) of the Commercial Computer Software -
 *  Restricted Rights at 48 CFR 52.227-19, as applicable.
 *
 *  Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
 *
 */

#ifndef _ONEWIRE_API_H
#define _ONEWIRE_API_H

#ifdef __cplusplus
extern "C"
{
#endif

/*ad*
 * 1-Wire speed modes and access modes which are passed in the @link naOnewireOpen 
 * and @link naOnewireIoctl calls. 
 *
 * @external
 * @category BSP:Device_Drivers:ONEWIRE_API
 * @since 7.4
 * @name naOnewireMode    "Onewire Modes"
 *
 * @see @link naOnewireOpen
 * @see @link naOnewireIoctl
 * @see @link NaOnewireConfig_t
 *
 * @param O_STANDARD     Sets the 1-Wire master to operate in standard speed
 * @param O_OVERDRIVE    Sets the 1-Wire master to operate in overdrive speed
 *                       when used with naOnewireIoctl 
 * @param O_ONEWIRE      Driver sets the curMode with this value when channel
 *                       opened successfully
 *
*ad*/
#define O_STANDARD      0x10000
#define O_OVERDRIVE     0x20000
#define O_ONEWIRE       0x40000

/*ad*
 * This 1-Wire IO control option is used to get the default configurations
 * used by the driver either in standard mode or in overdrive mode. 
 *
 * <bold>ioctl Argument</bold>
 *
 * Requires a pointer (of type @link NaOnewireConfig_t) to hold the default
 * configuration record used by the driver. If the curMode field of this 
 * pointer is set to O_OVERDRIVE then default overdrive configuration values 
 * will be returned. Otherwise default standard configuration values will be 
 * returned by the driver.
 *
 * <bold>ioctl return failure status and errno values</bold>
 *
 *     <list type="unordered">
 *      <item>  EINVAL  When NULL pointer is passed as argument </item>
 *      <item>  EBADF   When invalid fd is passed </item>
 *     </list>
 *
 * <bold>Sample usage:</bold>
 *
 * <example>
 * #include "netosIo.h"
 * #include "onewire_api.h"
 * 
 * void someSampleFunction (void)
 * {
 *     int fd, result;
 *     NaOnewireConfig_t  cnfg;
 *
 *     fd = open ("/onewire/0", O_RDWR);
 *     if (fd < 0)
 *     {
 *         return;
 *     }
 *
 *     cnfg.curMode = O_OVERDRIVE;
 *     result = ioctl(fd, NA_ONEWIRE_GET_DFLT, (char *)&cnfg);
 *     if (result < 0)
 *     {
 *         return;
 *     }
 * }
 *
 * </example>
 *
 * @external
 * @category BSP:Device_Drivers:ONEWIRE_API
 * @since 7.4
 *
 * @see @link naOnewireIoctl
 * @see @link ioctl
 *
*ad*/
#define NA_ONEWIRE_GET_DFLT		1


/*ad*
 * This 1-Wire IO control option is used to set the default configurations
 * either to standard mode or in overdrive mode. 
 *
 * <bold>ioctl Argument</bold>
 *
 * Requires a pointer of type unsigned to pass the default mode (either 
 * O_STANDARD or O_OVERDRIVE) for which driver configuration values will set.  
 *
 * <bold>ioctl return failure status and errno values</bold>
 *
 *     <list type="unordered">
 *      <item>  EINVAL  When NULL pointer is passed as argument or failed to
 *                      set default configuration value </item>
 *      <item>  EBADF   When invalid fd is passed </item>
 *     </list>
 *
 * <bold>Sample usage:</bold>
 *
 * This sample code tries to change the speed to overdrive in DS2431 memory 
 * device
 *
 * <example>
 * #include "netosIo.h"
 * #include "onewire_api.h"
 * 
 * void someSampleFunction (void)
 * {
 *     int fd;
 *     unsigned presence, mode = O_OVERDRIVE;
 *     unsigned char buf;
 *
 *     fd = open ("/onewire/0", O_RDWR);
 *     if (fd < 0)
 *     {
 *         return;
 *     }
 *
 *     // issue reset in standard speed
 *     if (ioctl(handle, NA_ONEWIRE_RESET, (char *)&presence) < 0)
 *         return;
 *
 *     if (presence == 0)
 *     {
 *         printf("No device found on channel 0\n");
 *         return;    
 *     }
 *   
 *     buff = 0x3C;  // overdrive skip rom
 *     if (write(handle, buff, 1) != 1)
 *         return;
 *
 *     if (ioctl(handle, NA_ONEWIRE_SET_DFLT, (char *)&mode) < 0)
 *         return;
 *
 *     // issue reset in overdrive speed
 *     if (ioctl(handle, NA_ONEWIRE_RESET, (char *)&presence) < 0)
 *         return;
 * }
 *
 * </example>
 *
 * @external
 * @category BSP:Device_Drivers:ONEWIRE_API
 * @since 7.4
 *
 * @see @link naOnewireIoctl
 * @see @link ioctl
 *
*ad*/
#define NA_ONEWIRE_SET_DFLT		2


/*ad*
 * This 1-Wire IO control option is used to get the current configuration 
 * values used by the driver. 
 *
 * <bold>ioctl Argument</bold>
 *
 * Requires a pointer (of type @link NaOnewireConfig_t) to hold the driver
 * configuration value. 
 *
 * <bold>ioctl return failure status and errno values</bold>
 *
 *     <list type="unordered">
 *      <item>  EINVAL  When NULL pointer is passed as argument </item>
 *      <item>  EBADF   When invalid fd is passed </item>
 *     </list>
 *
 * <bold>Sample usage:</bold>
 *
 * <example>
 * #include "netosIo.h"
 * #include "onewire_api.h"
 * 
 * void someSampleFunction (void)
 * {
 *     int fd, result;
 *     NaOnewireConfig_t  cnfg;
 *
 *     fd = open ("/onewire/0", O_RDWR);
 *     if (fd < 0)
 *     {
 *         return;
 *     }
 *
 *     result = ioctl(fd, NA_ONEWIRE_GET_CNFG, (char *)&cnfg);
 *     if (result < 0)
 *     {
 *         return;
 *     }
 * }
 *
 * </example>
 *
 * @external
 * @category BSP:Device_Drivers:ONEWIRE_API
 * @since 7.4
 *
 * @see @link naOnewireIoctl
 * @see @link ioctl
 *
*ad*/
#define NA_ONEWIRE_GET_CNFG		3

/*ad*
 * This 1-Wire IO control option is used to set the current configuration 
 * values in the driver. 
 *
 * <bold>ioctl Argument</bold>
 *
 * Requires a pointer (of type @link NaOnewireConfig_t) to pass the 
 * configuration value to update in the driver. 
 *
 * <bold>ioctl return failure status and errno values</bold>
 *
 *     <list type="unordered">
 *      <item>  EINVAL  When NULL pointer is passed as argument or failed to
 *                      configure the specified value </item>
 *      <item>  EBADF   When invalid fd is passed </item>
 *     </list>
 *
 * <bold>Sample usage:</bold>
 *
 * <example>
 * #include "netosIo.h"
 * #include "onewire_api.h"
 * 
 * void someSampleFunction (void)
 * {
 *     int fd, result;
 *     NaOnewireConfig_t  cnfg;
 *
 *     fd = open ("/onewire/0", O_RDWR);
 *     if (fd < 0)
 *     {
 *         return;
 *     }
 *
 *     result = ioctl(fd, NA_ONEWIRE_GET_CNFG, (char *)&cnfg);
 *     if (result < 0)
 *     {
 *         return;
 *     }
 *
 *     cnfg.tResetLow = 600; // set to 600 micro seconds
 *     result = ioctl(fd, NA_ONEWIRE_SET_CNFG, (char *)&cnfg);
 *     if (result < 0)
 *     {
 *         return;
 *     }
 *     
 * }
 *
 * </example>
 *
 * @external
 * @category BSP:Device_Drivers:ONEWIRE_API
 * @since 7.4
 *
 * @see @link naOnewireIoctl
 * @see @link ioctl
 *
*ad*/
#define NA_ONEWIRE_SET_CNFG		4

/*ad*
 * This 1-Wire IO control option is used to send reset to the connected 1-Wire
 * devices.
 *
 * <bold>ioctl Argument</bold>
 *
 * Requires a pointer of type unsigned to hold the presence pulse width in 
 * micro seconds. The zero pulse width means no device responded to the reset
 * command.   
 *
 * <bold>ioctl return failure status and errno values</bold>
 *
 *     <list type="unordered">
 *      <item>  EINVAL  When NULL pointer is passed as argument or failed to
 *                      send the reset command </item>
 *      <item>  EBADF   When invalid fd is passed </item>
 *     </list>
 *
 * <bold>Sample usage:</bold>
 *
 * Refer sample code in @link NA_ONEWIRE_SET_DFLT
 *
 * @external
 * @category BSP:Device_Drivers:ONEWIRE_API
 * @since 7.4
 *
 * @see @link naOnewireIoctl
 * @see @link ioctl
 *
*ad*/
#define NA_ONEWIRE_RESET		5

/*ad*
 * 1-Wire configuration structure which is passed in the @link naOnewireIoctl 
 * to access device configuration. 
 *
 * @external
 * @category BSP:Device_Drivers:ONEWIRE_API
 * @since 7.4
 *
 * @note All time values below are in micro seconds
 *
 * @param curMode   Holds the current operating mode
 * @param tSlot     Time slot value in microsecs     Std: 60 - 120 OD: 6 - 16 
 * @param tLow1     Duration of low pulse to write 1 Std: 1 - 15   OD: 1 - 2
 * @param tLow0     Duration of low pulse to write 0 Std: 60 - 120 OD: 6 - 16
 * @param tRec      Recovery time between bits       1 - no limit
 * @param tLowR     Duration of low pulse to read    Std: 1 - 15   OD: 1 - 2
 * @param tRdv      Duration to sample point         Std: 15       OD: 2
 * @param tRelease  Duration of release time at read Std: 0 - 45   OD: 0 - 4
 * @param tResetLow Reset low time                   Std: 480 -    OD: 48 - 80
 * @param genIoPin  FIM General IO pin number (0 - 7)
 *
 * @see @link naOnewireIoctl
 * @see @link naOnewireMode
 *
*ad*/
typedef struct NaOnewireConfig_t
{
    unsigned       curMode;
    unsigned short tSlot;
    unsigned short tLow1;
    unsigned short tLow0;
    unsigned short tRec;
    unsigned short tLowR;
    unsigned short tRdv;
    unsigned short tRelease;
    unsigned short tResetLow;
    unsigned short genIoPin;
}NaOnewireConfig_t;

int naOnewireOpen(int channel, unsigned mode);
int naOnewireClose(int channel);
int naOnewireRead(int channel, void * buffer, int length, int * bytesRead);
int naOnewireWrite(int channel, void * buffer, int length, int * bytesWritten);
int naOnewireIoctl(int channel, int request, char * arg);

#ifdef __cplusplus
}
#endif

#endif /* _ONEWIRE_API_H */



