interface/vmcs_host/vchost.h

   1 /*
   2 Copyright (c) 2012, Broadcom Europe Ltd
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are met:
   7     * Redistributions of source code must retain the above copyright
   8       notice, this list of conditions and the following disclaimer.
   9     * Redistributions in binary form must reproduce the above copyright
  10       notice, this list of conditions and the following disclaimer in the
  11       documentation and/or other materials provided with the distribution.
  12     * Neither the name of the copyright holder nor the
  13       names of its contributors may be used to endorse or promote products
  14       derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
  20 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 */
  27
  28 #ifndef VCHOST_H
  29 #define VCHOST_H
  30
  31 #include "vchost_platform_config.h"
  32 #include "vcfilesys_defs.h"
  33 #include "interface/vcos/vcos.h" //for VCHPRE_ abd VCHPOST_ macro's for func declaration
  34 #include "interface/vmcs_host/vc_fileservice_defs.h" // for VC_O_XXX file definitions
  35 #include "interface/vchi/vchi.h"
  36
  37 #define UNUSED_PARAMETER(x) ((void)(x))/* macro to suppress not use warning */
  38
  39 /*---------------------------------------------------------------------------*/
  40 /* Byte-swapping, dependent on host's orientation */
  41 /*---------------------------------------------------------------------------*/
  42
  43 #ifndef VC_HOST_IS_BIG_ENDIAN
  44 #define VC_HTOV32(val) (val)
  45 #define VC_HTOV16(val) (val)
  46 #define VC_VTOH32(val) (val)
  47 #define VC_VTOH16(val) (val)
  48 #else
  49 static unsigned long  VC_HTOV32(unsigned long val)  {
  50    return ((val<<24) | ((val&0xff00)<<8) | ((val>>8)&0xff00) | ((val>>24)&0xff)); }
  51 static unsigned short VC_HTOV16(unsigned short val) {
  52    return ((val<<8)|(val>>8)); }
  53 static unsigned long  VC_VTOH32(unsigned long val)  {
  54    return ((val<<24) | ((val&0xff00)<<8) | ((val>>8)&0xff00) | ((val>>24)&0xff)); }
  55 static unsigned short VC_VTOH16(unsigned short val) {
  56    return ((val<<8)|(val>>8)); }
  57 #endif
  58
  59 /*---------------------------------------------------------------------------*/
  60 /* Host port related functions */
  61 /*---------------------------------------------------------------------------*/
  62
  63 /* Boot a bin file from flash into RAM. Returns the id of the application running */
  64
  65 VCHPRE_ int VCHPOST_ vc_host_boot(char *cmd_line, void *binimg, int nbytes, int bootloader);
  66
  67 /* Perform any platform specific initialisations. */
  68
  69 VCHPRE_ int VCHPOST_ vc_host_init(void);
  70
  71 /* Read a multiple of 16 bytes from VideoCore. host_addr has no particular alignment,
  72    but it is important that it transfers the data in 16-bit chunks if this is possible. */
  73
  74 VCHPRE_ int VCHPOST_ vc_host_read_consecutive(void *host_addr, uint32_t vc_addr, int nbytes, int channel);
  75
  76 #ifdef VC_HOST_IS_BIG_ENDIAN
  77 // Reads from VideoCore with an implicit swap of each pair of bytes.
  78 VCHPRE_ int VCHPOST_ vc_host_read_byteswapped(void *host_addr, uint32_t vc_addr, int nbytes, int channel);
  79 #endif
  80
  81 /* Write a multiple of 16 bytes to VideoCore. host_addr has no particular alignment,
  82    but it is important that it transfers the data in 16-bit chunks if this is possible. */
  83
  84 VCHPRE_ int VCHPOST_ vc_host_write_consecutive(uint32_t vc_addr, void *host_addr, int nbytes, int channel);
  85
  86 #ifdef VC_HOST_IS_BIG_ENDIAN
  87 // Write to VideoCore with an implicit swap of each pair of bytes.
  88 VCHPRE_ int VCHPOST_ vc_host_write_byteswapped(uint32_t vc_addr, void *host_addr, int nbytes, int channel);
  89 #endif
  90
  91 /* Send an interrupt to VideoCore. */
  92
  93 VCHPRE_ int VCHPOST_ vc_host_send_interrupt(int channel);
  94
  95 /* Wait for an interrupt from VideoCore. This can return immediately if applications
  96    are happy to busy-wait. */
  97
  98 VCHPRE_ int VCHPOST_ vc_host_wait_interrupt(void);
  99
 100 /* Tell the host to act on or ignore interrupts. */
 101
 102 VCHPRE_ void VCHPOST_ vc_host_interrupts(int on);
 103
 104 /* Function called when there is some kind of internal error. Breakpoints can be set on
 105    this for debugging. */
 106
 107 VCHPRE_ void VCHPOST_ vc_error(void);
 108
 109
 110 /*---------------------------------------------------------------------------*/
 111 /* Event (interrupt) related functions */
 112 /*---------------------------------------------------------------------------*/
 113
 114 // Minimum number of event objects an implementation should support.
 115 // Sufficient for 2 per 8 interfaces/services + 4 others
 116 #define VC_EVENT_MAX_NUM  20
 117
 118 /* Create (and clear) an event.  Returns a pointer to the event object. */
 119 VCHPRE_ void * VCHPOST_ vc_event_create(void);
 120
 121 /* Wait for an event to be set, blocking until it is set.
 122    Only one thread may be waiting at any one time.
 123    The event is automatically cleared on leaving this function. */
 124 VCHPRE_ void VCHPOST_ vc_event_wait(void *sig);
 125
 126 /* Reads the state of an event (for polling systems) */
 127 VCHPRE_ int VCHPOST_ vc_event_status(void *sig);
 128
 129 /* Forcibly clears any pending event */
 130 VCHPRE_ void VCHPOST_ vc_event_clear(void *sig);
 131
 132 /* Sets an event - can be called from any thread */
 133 VCHPRE_ void VCHPOST_ vc_event_set(void *sig);
 134
 135 /* Register the calling task to be notified of an event. */
 136 VCHPRE_ void VCHPOST_ vc_event_register(void *ievent);
 137
 138 /* Set events to block, stopping polling mode. */
 139 VCHPRE_ void VCHPOST_ vc_event_blocking(void);
 140
 141 /*---------------------------------------------------------------------------*/
 142 /* Semaphore related functions */
 143 /*---------------------------------------------------------------------------*/
 144
 145 // Minimum number of locks an implementation should support.
 146
 147 #define VC_LOCK_MAX_NUM 32
 148
 149 // Create a lock. Returns a pointer to the lock object. A lock is initially available
 150 // just once.
 151
 152 VCHPRE_ void * VCHPOST_ vc_lock_create(void);
 153
 154 // Obtain a lock. Block until we have it. Locks are not re-entrant for the same thread.
 155
 156 VCHPRE_ void VCHPOST_ vc_lock_obtain(void *lock);
 157
 158 // Release a lock. Anyone can call this, even if they didn't obtain the lock first.
 159
 160 VCHPRE_ void VCHPOST_ vc_lock_release(void *lock);
 161
 162 /*---------------------------------------------------------------------------*/
 163 /* File system related functions */
 164 /*---------------------------------------------------------------------------*/
 165
 166 // Initialises the host dependent file system functions for use
 167 VCHPRE_ void VCHPOST_ vc_hostfs_init(void);
 168 VCHPRE_ void VCHPOST_ vc_hostfs_exit(void);
 169
 170 // Low level file system functions equivalent to close(), lseek(), open(), read() and write()
 171 VCHPRE_ int VCHPOST_ vc_hostfs_close(int fildes);
 172
 173 VCHPRE_ long VCHPOST_ vc_hostfs_lseek(int fildes, long offset, int whence);
 174
 175 VCHPRE_ int64_t VCHPOST_ vc_hostfs_lseek64(int fildes, int64_t offset, int whence);
 176
 177 VCHPRE_ int VCHPOST_ vc_hostfs_open(const char *path, int vc_oflag);
 178
 179 VCHPRE_ int VCHPOST_ vc_hostfs_read(int fildes, void *buf, unsigned int nbyte);
 180
 181 VCHPRE_ int VCHPOST_ vc_hostfs_write(int fildes, const void *buf, unsigned int nbyte);
 182
 183 // Ends a directory listing iteration
 184 VCHPRE_ int VCHPOST_ vc_hostfs_closedir(void *dhandle);
 185
 186 // Formats the drive that contains the given path
 187 VCHPRE_ int VCHPOST_ vc_hostfs_format(const char *path);
 188
 189 // Returns the amount of free space on the drive that contains the given path
 190 VCHPRE_ int VCHPOST_ vc_hostfs_freespace(const char *path);
 191 VCHPRE_ int64_t VCHPOST_ vc_hostfs_freespace64(const char *path);
 192
 193 // Gets the attributes of the named file
 194 VCHPRE_ int VCHPOST_ vc_hostfs_get_attr(const char *path, fattributes_t *attr);
 195
 196 // Creates a new directory
 197 VCHPRE_ int VCHPOST_ vc_hostfs_mkdir(const char *path);
 198
 199 // Starts a directory listing iteration
 200 VCHPRE_ void * VCHPOST_ vc_hostfs_opendir(const char *dirname);
 201
 202 // Directory listing iterator
 203 VCHPRE_ struct dirent * VCHPOST_ vc_hostfs_readdir_r(void *dhandle, struct dirent *result);
 204
 205 // Deletes a file or (empty) directory
 206 VCHPRE_ int VCHPOST_ vc_hostfs_remove(const char *path);
 207
 208 // Renames a file, provided the new name is on the same file system as the old
 209 VCHPRE_ int VCHPOST_ vc_hostfs_rename(const char *oldfile, const char *newfile);
 210
 211 // Sets the attributes of the named file
 212 VCHPRE_ int VCHPOST_ vc_hostfs_set_attr(const char *path, fattributes_t attr);
 213
 214 // Truncates a file at its current position
 215 VCHPRE_ int VCHPOST_ vc_hostfs_setend(int fildes);
 216
 217 // Returns the total amount of space on the drive that contains the given path
 218 VCHPRE_ int VCHPOST_ vc_hostfs_totalspace(const char *path);
 219 VCHPRE_ int64_t VCHPOST_ vc_hostfs_totalspace64(const char *path);
 220
 221 // Return millisecond resolution system time, only used for differences
 222 VCHPRE_ int VCHPOST_ vc_millitime(void);
 223
 224 // Invalidates any cluster chains in the FAT that are not referenced in any directory structures
 225 VCHPRE_ void VCHPOST_ vc_hostfs_scandisk(const char *path);
 226
 227 // Checks whether or not a FAT filesystem is corrupt or not. If fix_errors is TRUE behaves exactly as vc_filesys_scandisk.
 228 VCHPRE_ int VCHPOST_ vc_hostfs_chkdsk(const char *path, int fix_errors);
 229
 230 /*---------------------------------------------------------------------------*/
 231 /* These functions only need to be implemented for the test system. */
 232 /*---------------------------------------------------------------------------*/
 233
 234 // Open a log file.
 235 VCHPRE_ void VCHPOST_ vc_log_open(const char *fname);
 236
 237 // Flush any pending data to the log file.
 238 VCHPRE_ void VCHPOST_ vc_log_flush(void);
 239
 240 // Close the log file.
 241 VCHPRE_ void VCHPOST_ vc_log_close(void);
 242
 243 // Log an error.
 244 VCHPRE_ void VCHPOST_ vc_log_error(const char *format, ...);
 245
 246 // Log a warning.
 247 VCHPRE_ void VCHPOST_ vc_log_warning(const char *format, ...);
 248
 249 // Write a message to the log.
 250 VCHPRE_ void VCHPOST_ vc_log_msg(const char *format, ...);
 251
 252 // Flush the log.
 253 VCHPRE_ void VCHPOST_ vc_log_flush(void);
 254
 255 // Return the total number of warnings and errors logged.
 256 VCHPRE_ void VCHPOST_ vc_log_counts(int *warnings, int *errors);
 257
 258 // Wait for the specified number of microseconds. Used in test system only.
 259 VCHPRE_ void VCHPOST_ vc_sleep(int ms);
 260
 261 // Get a time value in milliseconds. Used for measuring time differences
 262 VCHPRE_ uint32_t VCHPOST_ vc_time(void);
 263
 264 // Check timing functions are available. Use in calibrating tests.
 265 VCHPRE_ int VCHPOST_ calibrate_sleep (const char *data_dir);
 266
 267 /*---------------------------------------------------------------------------*/
 268 /* Functions to allow dynamic service creation */
 269 /*---------------------------------------------------------------------------*/
 270
 271 VCHPRE_ void VCHPOST_ vc_host_get_vchi_state(VCHI_INSTANCE_T *initialise_instance, VCHI_CONNECTION_T **connection);
 272
 273 #endif