Add docstrings

src/core/hle/service/cam/cam.cpp

@@ -20,33 +20,81 @@ namespace CAM {
 
 static const u32 TRANSFER_BYTES = 5 * 1024;
 
+static bool driver_initialized = false;
+
 static Kernel::SharedPtr<Kernel::Event> completion_event;
 static Kernel::SharedPtr<Kernel::Event> interrupt_error_event;
-static Kernel::SharedPtr<Kernel::Event> vsync_interrupt_error_event;
+static Kernel::SharedPtr<Kernel::Event> vsync_interrupt_event;
 
+
+/**
+ * CAM_U::DriverInitialize service function
+ *
+ * This Function inits camera module.
+ *
+ *  Inputs:
+ *      None
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void DriverInitialize(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
+    completion_event            = Kernel::Event::Create(RESETTYPE_ONESHOT, "CAM_U::completion_event");
+    interrupt_error_event       = Kernel::Event::Create(RESETTYPE_ONESHOT, "CAM_U::interrupt_error_event");
+    vsync_interrupt_event       = Kernel::Event::Create(RESETTYPE_ONESHOT, "CAM_U::vsync_interrupt_eevent");
+
+    driver_initialized = true;
+
     cmd_buff[1]   = RESULT_SUCCESS.raw;
 
-    LOG_WARNING(Service_CAM, "(STUBBED) called");
+    LOG_TRACE(Service_CAM, "(STUBBED) called");
 }
 
+/**
+ * CAM_U::DriverFinalize service function
+ *
+ * This Function shutdown camera module.
+ *
+ *  Inputs:
+ *      None
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void DriverFinalize(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
+    completion_event            = nullptr;
+    interrupt_error_event       = nullptr;
+    vsync_interrupt_event       = nullptr;
+
+    driver_initialized = false;
+
     cmd_buff[1]   = RESULT_SUCCESS.raw;
 
     LOG_WARNING(Service_CAM, "(STUBBED) called");
 }
 
+/**
+ * CAM_U::SetTransferLines service function
+ *
+ * This Function sets the number of lines to transfer.
+ *
+ *  Inputs:
+ *      1 : For which port set the lines count
+ *      2 : Number of lines
+ *      3 : Width of captured image
+ *      4 : Height of captured image
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void SetTransferLines(Service::Interface* self) {
     u32* cmd_buff      = Kernel::GetCommandBuffer();
 
-    u8  port           = cmd_buff[1] & 0xFF;
+    Port port           = static_cast<Port>(cmd_buff[1] & 0xFF);
-    u16 transfer_lines = cmd_buff[2] & 0xFFFF;
+    s16  transfer_lines = cmd_buff[2] & 0xFFFF;
-    u16 width          = cmd_buff[3] & 0xFFFF;
+    s16  width          = cmd_buff[3] & 0xFFFF;
-    u16 height         = cmd_buff[4] & 0xFFFF;
+    s16  height         = cmd_buff[4] & 0xFFFF;
 
     cmd_buff[1]        = RESULT_SUCCESS.raw;
 
@@ -54,6 +102,18 @@ void SetTransferLines(Service::Interface* self) {
                 port, transfer_lines, width, height);
 }
 
+/**
+ * CAM_U::GetMaxLines service function
+ *
+ * This Function gets the max lines.
+ *
+ *  Inputs:
+ *      1 : Width of captured image
+ *      2 : Height of captured image
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ *      2 : Maximum lines to transfer
+ */
 void GetMaxLines(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
@@ -67,10 +127,21 @@ void GetMaxLines(Service::Interface* self) {
                 width, height, cmd_buff[2]);
 }
 
+/**
+ * CAM_U::GetBufferErrorInterruptEvent service function
+ *
+ * This Function gets the event, which signalled about buffer error.
+ *
+ *  Inputs:
+ *      1 : Which port detects event
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ *      3 : Event to signal of buffer error
+ */
 void GetBufferErrorInterruptEvent(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 port       = cmd_buff[1] & 0xFF;
+    Port port     = static_cast<Port>(cmd_buff[1] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
     cmd_buff[3]   = Kernel::g_handle_table.Create(interrupt_error_event).MoveFrom();
@@ -78,23 +149,46 @@ void GetBufferErrorInterruptEvent(Service::Interface* self) {
     LOG_WARNING(Service_CAM, "(STUBBED) called, port=%d", port);
 }
 
+/**
+ * CAM_U::GetVsyncInterruptEvent service function
+ *
+ * This Function gets the event, which signalled about Vsync interrupt.
+ *
+ *  Inputs:
+ *      1 : Which port detects Vsync interrupt
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ *      3 : Event to signal Vsync interrupt
+ */
 void GetVsyncInterruptEvent(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 port       = cmd_buff[1] & 0xFF;
+    Port port     = static_cast<Port>(cmd_buff[1] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
-    cmd_buff[3]   = Kernel::g_handle_table.Create(vsync_interrupt_error_event).MoveFrom();
+    cmd_buff[3]   = Kernel::g_handle_table.Create(vsync_interrupt_event).MoveFrom();
 
     LOG_WARNING(Service_CAM, "(STUBBED) called, port=%d", port);
 }
 
+/**
+ * CAM_U::SetSize service function
+ *
+ * This Function sets the resolution of selected cameras.
+ *
+ *  Inputs:
+ *      1 : Which camera to change size
+ *      2 : The resolution
+ *      3 : Context
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void SetSize(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 cam_select = cmd_buff[1] & 0xFF;
+    CameraSelect cam_select = static_cast<CameraSelect>(cmd_buff[1] & 0xFF);
-    u8 size       = cmd_buff[2] & 0xFF;
+    Size size               = static_cast<Size>(cmd_buff[2] & 0xFF);
-    u8 context    = cmd_buff[3] & 0xFF;
+    Context context         = static_cast<Context>(cmd_buff[3] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
 
@@ -102,10 +196,20 @@ void SetSize(Service::Interface* self) {
                 cam_select, size, context);
 }
 
+/**
+ * CAM_U::Activate service function
+ *
+ * This Function activates selected camera.
+ *
+ *  Inputs:
+ *      1 : Which camera to activate
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void Activate(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 cam_select = cmd_buff[1] & 0xFF;
+    CameraSelect cam_select = static_cast<CameraSelect>(cmd_buff[1] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
 
@@ -113,10 +217,21 @@ void Activate(Service::Interface* self) {
                 cam_select);
 }
 
+/**
+ * CAM_U::SetTrimming service function
+ *
+ * This Function enables or disables trimming.
+ *
+ *  Inputs:
+ *      1 : Port
+ *      2 : Enable/Disable
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void SetTrimming(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8   port     = cmd_buff[1] & 0xFF;
+    Port port     = static_cast<Port>(cmd_buff[1] & 0xFF);
     bool trim     = cmd_buff[2] & 0xFF;
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
@@ -124,27 +239,53 @@ void SetTrimming(Service::Interface* self) {
     LOG_WARNING(Service_CAM, "(STUBBED) called, port=%d, trim=%d", port, trim);
 }
 
+/**
+ * CAM_U::SetTrimmingParamsCenter service function
+ *
+ * This Function sets the trimming position.
+ *
+ *  Inputs:
+ *      1 : Port
+ *      2 : Trim width
+ *      2 : Trim height
+ *      2 : Captured image width
+ *      2 : Captured image height
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void SetTrimmingParamsCenter(Service::Interface* self) {
-    u32* cmd_buff = Kernel::GetCommandBuffer();
+    u32* cmd_buff  = Kernel::GetCommandBuffer();
 
-    u8  port      = cmd_buff[1] & 0xFF;
+    Port port      = static_cast<Port>(cmd_buff[1] & 0xFF);
-    s16 trimW     = cmd_buff[2] & 0xFFFF;
+    s16 trimWidth  = cmd_buff[2] & 0xFFFF;
-    s16 trimH     = cmd_buff[3] & 0xFFFF;
+    s16 trimHeight = cmd_buff[3] & 0xFFFF;
-    s16 camW      = cmd_buff[4] & 0xFFFF;
+    s16 camWidth   = cmd_buff[4] & 0xFFFF;
-    s16 camH      = cmd_buff[5] & 0xFFFF;
+    s16 camHeight  = cmd_buff[5] & 0xFFFF;
 
-    cmd_buff[1]   = RESULT_SUCCESS.raw;
+    cmd_buff[1]    = RESULT_SUCCESS.raw;
 
     LOG_WARNING(Service_CAM, "(STUBBED) called, port=%d, trimW=%d, trimH=%d, camW=%d, camH=%d",
-                port, trimW, trimH, camW, camH);
+                port, trimWidth, trimHeight, camWidth, camHeight);
 }
 
+/**
+ * CAM_U::FlipImage service function
+ *
+ * This Function sets the flipping for selected camera.
+ *
+ *  Inputs:
+ *      1 : Which camera will flip images
+ *      2 : Flipping
+ *      3 : Context
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void FlipImage(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 cam_select = cmd_buff[1] & 0xFF;
+    CameraSelect cam_select = static_cast<CameraSelect>(cmd_buff[1] & 0xFF);
-    u8 flip       = cmd_buff[2] & 0xFF;
+    Flip         flip       = static_cast<Flip>(cmd_buff[2] & 0xFF);
-    u8 context    = cmd_buff[3] & 0xFF;
+    Context      context    = static_cast<Context>(cmd_buff[3] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
 
@@ -155,8 +296,8 @@ void FlipImage(Service::Interface* self) {
 void SetFrameRate(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 cam_select = cmd_buff[1] & 0xFF;
+    CameraSelect cam_select = static_cast<CameraSelect>(cmd_buff[1] & 0xFF);
-    u8 frame_rate = cmd_buff[2] & 0xFF;
+    FrameRate    frame_rate = static_cast<FrameRate>(cmd_buff[2] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
 
@@ -164,19 +305,42 @@ void SetFrameRate(Service::Interface* self) {
                 cam_select, frame_rate);
 }
 
+/**
+ * CAM_U::GetSuitableY2rStandardCoefficient service function
+ *
+ * This Function gets suitable Y2r standart coefficient.
+ *
+ *  Inputs:
+ *      None
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ *      2 : Standart coefficient
+ */
 void GetSuitableY2rStandardCoefficient(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
+    using namespace Y2R_U;
     cmd_buff[1]   = RESULT_SUCCESS.raw;
-    cmd_buff[2]   = 0;
+    cmd_buff[2]   = static_cast<u32>(StandardCoefficient::ITU_Rec601);
 
     LOG_WARNING(Service_CAM, "(STUBBED) called");
 }
 
+/**
+ * CAM_U::GetTransferBytes service function
+ *
+ * This Function gets the number of bytes to transfer on selected port.
+ *
+ *  Inputs:
+ *      1 : Port
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ *      2 : Number of bytes to transfer
+ */
 void GetTransferBytes(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 port       = cmd_buff[1] & 0xFF;
+    Port port     = static_cast<Port>(cmd_buff[1] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
     cmd_buff[2]   = TRANSFER_BYTES;
@@ -184,13 +348,27 @@ void GetTransferBytes(Service::Interface* self) {
     LOG_WARNING(Service_CAM, "(STUBBED) called, port=%d", port);
 }
 
+/**
+ * CAM_U::SetReceiving service function
+ *
+ * This Function sets the output buffer for .
+ *
+ *  Inputs:
+ *      1 : Output buffer address
+ *      2 : Port
+ *      3 : Size of image
+ *      4 : Portion of data, transferred at once
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ *      3 : Event, signalled about completion
+ */
 void SetReceiving(Service::Interface* self) {
     u32* cmd_buff  = Kernel::GetCommandBuffer();
 
-    u32 dest       = cmd_buff[1]; // void*
+    u32 dest       = cmd_buff[1];
-    u8  port       = cmd_buff[2] & 0xFF;
+    Port port      = static_cast<Port>(cmd_buff[2] & 0xFF);
     u32 image_size = cmd_buff[3];
-    u16 trans_unit = cmd_buff[4] & 0xFFFF;
+    s16 trans_unit = cmd_buff[4] & 0xFFFF;
 
     cmd_buff[1]    = RESULT_SUCCESS.raw;
     cmd_buff[3]    = Kernel::g_handle_table.Create(completion_event).MoveFrom();
@@ -199,38 +377,66 @@ void SetReceiving(Service::Interface* self) {
                 dest, port, image_size, trans_unit);
 }
 
+/**
+ * CAM_U::StartCapture service function
+ *
+ * This Function starts capturing on selected port.
+ *
+ *  Inputs:
+ *      1 : Port to start capturing
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void StartCapture(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 port       = cmd_buff[1] & 0xFF;
+    Port port     = static_cast<Port>(cmd_buff[1] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
 
     LOG_WARNING(Service_CAM, "(STUBBED) called, port=%d", port);
 }
 
+/**
+ * CAM_U::StopCapture service function
+ *
+ * This Function stops capturing on selected port.
+ *
+ *  Inputs:
+ *      1 : Port to stop capturing
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void StopCapture(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 port       = cmd_buff[1] & 0xFF;
+    Port port     = static_cast<Port>(cmd_buff[1] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
 
     LOG_WARNING(Service_CAM, "(STUBBED) called, port=%d", port);
 }
 
+/**
+ * CAM_U::PlayShutterSound service function
+ *
+ * This Function plays the selected shutter sound.
+ *
+ *  Inputs:
+ *      1 : Sound ID
+ *  Outputs:
+ *      1 : Result of function, 0 on success, otherwise error code
+ */
 void PlayShutterSound(Service::Interface* self) {
     u32* cmd_buff = Kernel::GetCommandBuffer();
 
-    u8 sound_id   = cmd_buff[1] & 0xFF;
+    ShutterSoundType sound_id   = static_cast<ShutterSoundType>(cmd_buff[1] & 0xFF);
 
     cmd_buff[1]   = RESULT_SUCCESS.raw;
 
     LOG_WARNING(Service_CAM, "(STUBBED) called, sound_id=%d", sound_id);
 }
 
-
-
 void Init() {
     using namespace Kernel;
 
@@ -238,16 +444,10 @@ void Init() {
     AddService(new CAM_Q_Interface);
     AddService(new CAM_S_Interface);
     AddService(new CAM_U_Interface);
-
-    completion_event            = Kernel::Event::Create(RESETTYPE_ONESHOT, "CAM_U::completion_event");
-    interrupt_error_event       = Kernel::Event::Create(RESETTYPE_ONESHOT, "CAM_U::interrupt_error_event");
-    vsync_interrupt_error_event = Kernel::Event::Create(RESETTYPE_ONESHOT, "CAM_U::vsync_interrupt_error_event");
 }
 
 void Shutdown() {
-    completion_event            = nullptr;
+
-    interrupt_error_event       = nullptr;
-    vsync_interrupt_error_event = nullptr;
 }
 
 } // namespace CAM

src/core/hle/service/cam/cam.h

@@ -6,10 +6,77 @@
 
 #include "core/hle/kernel/kernel.h"
 #include "core/hle/service/service.h"
+#include "core/hle/service/y2r_u.h"
 
 namespace Service {
 namespace CAM {
 
+enum Port {
+    PORT_NONE = 0,
+    PORT_CAM1 = 1,
+    PORT_CAM2 = 2,
+    PORT_BOTH = PORT_CAM1 | PORT_CAM2
+};
+
+enum CameraSelect {
+    SELECT_NONE      = 0,
+    SELECT_OUT1      = 1,
+    SELECT_IN1       = 2,
+    SELECT_OUT2      = 3,
+    SELECT_IN1_OUT1  = SELECT_OUT1 | SELECT_IN1,
+    SELECT_OUT1_OUT2 = SELECT_OUT1 | SELECT_OUT2,
+    SELECT_IN1_OUT2  = SELECT_IN1 | SELECT_OUT2 ,
+    SELECT_ALL       = SELECT_OUT1 | SELECT_IN1 | SELECT_OUT2
+};
+
+enum Context {
+    CONTEXT_NONE = 0,
+    CONTEXT_A    = 1,
+    CONTEXT_B    = 2,
+    CONTEXT_BOTH = CONTEXT_A | CONTEXT_B
+};
+
+enum Flip {
+    FLIP_NONE       = 0,
+    FLIP_HORIZONTAL = 1,
+    FLIP_VERTICAL   = 2,
+    FLIP_REVERSE    = 3
+};
+
+enum Size {
+    SIZE_VGA            = 0,
+    SIZE_QVGA           = 1,
+    SIZE_QQVGA          = 2,
+    SIZE_CIF            = 3,
+    SIZE_QCIF           = 4,
+    SIZE_DS_LCD         = 5,
+    SIZE_DS_LCDx4       = 6,
+    SIZE_CTR_TOP_LCD    = 7,
+    SIZE_CTR_BOTTOM_LCD = SIZE_QVGA
+};
+
+enum FrameRate {
+    FRAME_RATE_15       = 0,
+    FRAME_RATE_15_TO_5  = 1,
+    FRAME_RATE_15_TO_2  = 2,
+    FRAME_RATE_10       = 3,
+    FRAME_RATE_8_5      = 4,
+    FRAME_RATE_5        = 5,
+    FRAME_RATE_20       = 6,
+    FRAME_RATE_20_TO_5  = 7,
+    FRAME_RATE_30       = 8,
+    FRAME_RATE_30_TO_5  = 9,
+    FRAME_RATE_15_TO_10 = 10,
+    FRAME_RATE_20_TO_10 = 11,
+    FRAME_RATE_30_TO_10 = 12
+};
+
+enum ShutterSoundType {
+    SHUTTER_SOUND_TYPE_NORMAL    = 0,
+    SHUTTER_SOUND_TYPE_MOVIE     = 1,
+    SHUTTER_SOUND_TYPE_MOVIE_END = 2
+};
+
 void DriverInitialize(Service::Interface* self);
 void DriverFinalize(Service::Interface* self);
 void GetMaxLines(Service::Interface* self);